Application Development


Appendix A . Development Utilities

This appendix describes utilities that are useful in the development process:


bin2c

Converts binary files into C data structures

bin2c [-fluv] asciiFile inputFile ...

-f
Overwrite an existing output file.

-l
Convert filenames sent to output to lower case.

-u
Make array of unsigned chars instead of chars.

-v
Generate list of files processed.

asciiFile
Name of the output file.

inputFile
Name of the input file.

Description

bin2c converts Panther binaries—such as screens, menus, and JPL modules—into C character arrays. When bin2c creates the ASCII C file, it generate an array for each of the input files. An array in the file has one of these two forms:

char inputFile[] = { contents of file };
unsigned char inputFile[] = { contents of file };

where inputFile is the name of the source binary file with its path and extension stripped off. If you use the -l option, inputFile is converted to lower case.

Files created with bin2c arrays can be compiled, linked with your application, and added to the memory-resident form list with sm_formlist. For more information on memory-resident lists, refer to this function and to page 42-8. The following files can be made memory-resident:

You cannot convert a file back to its original binary form after using bin2c. Panther provides other utilities that permit two-way conversions between binary and ASCII formats. For screens, these utilities are bin2hex and f2asc.


bin2hex

Converts binary screens to hexadecimal ASCII file

bin2hex -c[flv] asciiFile screen ...
bin2hex -x[flv] asciiFile

-c
Create an ASCII file from one or more screens.

-f
Overwrite an existing file.

-l
Convert filenames in output to lower case.

-v
Generate list of files processed.

-x
Extract all screens contained in an ASCII source; selective extraction is not supported.

asciiFile
Specifies the name of the ASCII output file or ASCII input file if using the -x option.

screen
Name of a screen to convert to hexadecimal.

Description

bin2hex converts binary files to and from hexadecimal to let you port Panther screens across different systems. By default, the screen editor creates binary screen files.

With the -c option, all named binary input files (screen) are converted to hexadecimal ASCII and added to asciiFile. Path names are stripped off; extensions are left intact. With the -x option, bin2hex extracts each screen in the specified asciiFile and puts each file, in binary format, in the current directory.

Selective extraction of screens from asciiFile is not supported. Only one argument is supported with the -x option; additional arguments are ignored.


binherit

Updates screens and reports with inherited property values from repositories

binherit [ -r repository ] [ -v level ] [ -u ] -l library [ libMember ...]

-l library
Name of the library from which to read for updating all members or individual library members (libMember).

-r repository
Name of the repository from which to inherit. If not specified, binherit checks the value of SMDICNAME. If the variable is not set, the utility seeks a repository named data.dic in the current directory and along SMPATH. If unable to find the repository, an error is issued.

-u
Update the screens/reports as well as listing the differences.

-v level
Specify level of detail to report: 0: No reporting, 1: List screens as they are processed (the default setting), 2: List screens and widgets as they are processed, 3: List screens, widgets, and properties as they are processed.

Description

binherit opens the named library and searches all or specified library members for widgets having the Inherit From property set to a repository entry in the open repository, for example, titles!title_id. For those widgets, it compares the inherited property values with the values in the repository. The properties that have inheritance disabled are ignored.

If the screen's Inherit From property is set, it compares the values in the inherited screen properties with the corresponding values in the repository.

If the -u option is specified, it updates the file with the repository value; however, this option will be ignored for members of libraries that can only be opened read-only.

Errors

The following table describes possible errors, their causes, and the corrective action to take:

No repository is open.

Cause

Repository could not be opened either because: the name specified after the -r option could not be found or opened, the -r option was not used and the value in SMDICNAME was not set or found, or a repository having the name data.dic could not be found.

Action

Use the -r option, ensuring that the spelling and location of the specified repository is correct.

Not a Panther repository.

Cause

File specified after the -r option was incorrect.

Action

Check the spelling and location of the specified repository.

Unable to inherit property propertyName for objectId

Cause

The object listed in the Inherit From property cannot be found in the current repository.

Action

Make sure the current repository was specified. Also, check the Inherit From property for the object.

Unable to open Panther library.

Cause

Unable to find or open the specified library.

Action

If the library is not in the current directory, include the path name.

Unable to open Panther repository.

Cause

Unable to find the specified repository.

Action

If the repository is not in the current directory, include the path name.

Verbosity (-v) must be 0, 1, 2, or 3

Cause

An invalid value followed the -v option.

Action

Supply one of the listed values in the command line.


cmap2bin

Converts configuration map files to binary

cmap2bin [-pv] [-e ext] mapFile ...

-e ext
Use the specified ext extension in the output file name instead of the default bin extension.

-p
Place the output file in the same directory as the input file.

-v
Generate a list of files processed.

mapFile
Name of ASCII configuration map file; more than one input file can be specified.

Description

cmap2bin converts one or more ASCII configuration map files to a binary format for use by Panther.

cmap2bin automatically appends the binary file name with the bin extension unless you specify a different extension with the -e option. It places the binary output file in the directory where you run the utility unless you use the -p option.

Errors

The following table describes possible errors, their cause, and the corrective action to take:

Attribute %s not allowed in a background scheme.

Cause

Attribute specification cannot be applied to a particular background scheme.

Action

Remove the attribute specification and rerun cmap2bin.

Background attributes %s in extended color definitions.

Cause

Background attributes apply only to Panther basic colors.

Action

Remove background attribute specification and rerun cmap2bin.

Background color %s in a foreground scheme

Cause

A background color specification (begins with B_) was named in a foreground scheme.

Action

Edit foreground scheme to use a foreground color specification and rerun cmap2bin.

CONTAINER attribute not allowed in foreground scheme

Cause

Container specification was indicated in a foreground scheme.

Action

Edit foreground scheme that uses CONTAINER specification and rerun cmap2bin.

CONTAINER is used for background only.

Cause

Container specification was indicated.

Action

Edit foreground scheme that uses CONTAINER specification and rerun cmap2bin.

Error opening file '%s'.

Cause

An error was encountered when attempting open the specified file.

Action

Confirm that the file is readable and that the target directory can be written.

Extra equal sign

Cause

A line in the configuration map file includes an extra equal sign in the specification.

Action

Correct the line and rerun cmap2bin.

Illegal color scheme name %s

Cause

Color specification cannot be resolved.

Action

Check mapFile for illegal color name, edit the file and rerun cmap2bin.

Missing equal sign

Cause

A line in the configuration map file has no equal sign following the tag.

Action

Correct the input and rerun cmap2bin.

No other attribute allowed if CONTAINER is specified

Cause

A display attribute was assigned to a background color scheme identified as CONTAINER. A CONTAINER specification means the object adopts the color and attributes of it container.

Action

Either remove the attribute specification or change the CONTAINER specification to a specific color.


f2asc

Converts screens, service components and reports between binary and ASCII format

f2asc -a[cfn] [-i headerFile] asciiFile binaryFile ...
f2asc -b[f] asciiFile

-a
Create ASCII listing of one or more screens, service components and/or reports.

-b
Extract all binary files (screens, service components, reports) from an ASCII listing. This option does not accept an output filename.

-c
Do not generate comment lines (-a option only).

-f
Overwrite an existing file.

-i headerFile
Include specified headerFile at beginning of ASCII output.

-n
Do not sort PI edits in the ASCII file (backwards compatibility option).

asciiFile
With -a option, name of the file to receive ASCII version of binaryFile. With -b option, name ASCII file to convert back to binary format.

binaryFile
Filename of screen, service component or report to convert to ASCII.

Description

f2asc lets you create an ASCII listing of the contents of a screen, service component or report (-a option); and convert it back to binary format using the -b option. The editor creates and uses binary files only.

With -a, you must specify the name of at least one screen/component/report (or use wildcard characters). With -b, names are ignored. The -b option automatically extracts all files from the specified asciiFile.f2asc is typically used for documenting applications. It is also useful for editing tasks that are best performed by text editors—for example, global search and replace operations.

ASCII Output

The text file generated by f2asc describes the contents of the screen, service component or report—the widgets that compose it and their respective properties. It is broken into sections by object type, starting with the screen/component/report itself, and identifies the object by name, if it has one. Subsequent statements in the section describe each object through attribute keywords.

A:layoutAreaName
A layout area in a report.

B:widgetName
A non-field widget: box, line, grid, graph, report area or tab deck.

C:logicalKey
Identifies a logical key that is associated with a control string. The subsequent ACTION statement contains the control string itself.

F:fieldName
The name of a field (including text, check box, push button, link, dynamic label, and dynamic output widgets).

G:groupName
Selection group.

I:
Service component's interface definition.

L:staticLabelName
Static label.

R:reportName
Name of the report. All report files begin with this entry.

S:screenName
Name of the screen. All screen files begin with this entry.

T:tableViewName
Table view widget.

Y:syncGroup
Synchronized scrolling group.

Comment lines begin with a pound (#) character. For example:

# NUMBER=1

Two types of expressions are used to specify the properties:

There are two types of keywords describing object properties, flags and values:


formlib

Creates and maintains libraries and repositories

formlib -c [-fluv] library [filename ...]
formlib -r [-luv] library filename [filename ...]
formlib -x [-fluv] library [memberName...]
formlib -{d|t} [-luv] library [memberName ...]
formlib -{e|i|m|o|s|w} [-v] library
formlib -g cfgStr [-v] library

-c
Create a new library/repository that optionally contains the files named (filename ...). If no files are specified, an empty library is created.

-d
Delete the named members from the library/repository.

-e
Configure the library/repository for external file locking.

-f
Overwrite a library member or repository entry.

-g cfgStr
Define a configuration management string; begins with the name of your configuration management system—either sccs, pvcs or scpi (in lower case). For information about source control management options, refer to page 10-5.

-i
Configure the library/repository for internal (operating system) file locking.

-l
Convert filenames to lowercase before processing.

-m
Compact the library by removing unused space. The original library is kept as libname.old. The compacted library will have read-write permissions and be configured to use internal file locking.

-o
Configure the library/repository to be read-only. This operation is not reversible unless the library is compacted using formlib's -m option.

-r
Replace/add the named files to the library/repository.

-s
Synchronize the specified library with the source code management directory.

-t
Generate a list of the library/repository contents.

-u
Convert filenames to uppercase before processing.

-v
Display information in verbose mode. Generates a list of files processed. When used in conjunction with the -t option, produces a detailed listing of the library contents.

-w
Upgrade a JAM library/repository to Panther format.

-x
Extract (copy) the named files from specified library/repository. If none are named, all are extracted. Do not include wildcard specifiers in the filename.

filename
Name of file to be included in library or repository.

library
Name of library/repository.

memberName
Name of library member or repository entries.

Description

formlib lets you create and maintain libraries/repositories in which you store application components, such as screens, menus, and JPL files. You can store ASCII files in a Panther library; however, only binary files are accessible at runtime or through the screen editor.

formlib can also be used to maintain and get information about libraries and repositories; for example, you can put a library/repository under source management control, or get a list of its contents.

File specifications can include any wildcard or pattern-matching symbols that are valid for your operating system. For example, this command puts all files with the .rpt extension into the library screens.lib:

formlib -c screens.lib *.rpt

Library member specifications must be explicit; no wildcards can be used.

Case Sensitivity

The -l and -u options are useful for operating systems like UNIX that are case-sensitive. For example, the following UNIX command creates the library new.lib and adds all .scr files in the current directory to it; all files receive lowercase names—for example, MAIN.SCR becomes main.scr.

formlib -cl new.lib *.[Ss][Cc][Rr]
File Locking

Access to libraries requires both read and write locking. Locking of libraries is unrelated to source control management, as the latter affects access to individual library members (and their archived versions) during development, whereas the former controls access on an as-needed basis to the library file as a unit during development and at runtime.

Libraries require write locks to provide exclusive access during the brief moments when a library is being written to. Read locks allow others to read from the library, but prevent the library from being written to while it is being read. Read-only libraries that have been marked so (via the -o option) do not need any locking at all since they cannot be written to under any circumstances.

You can configure a library to use either of two file-locking schemes. By default, the internal (native operating system) file locking system is used. Use the -e option to use an external locking scheme. External locking can be used if internal locking is not available in your environment. It creates an empty exclusive-access file called libname.jlk to implement write locking, and keeps a count of the current readers in a shared read lock file called libname.rlk. The .jlk and .rlk files are created in the same directory as the library. They are checked or modified when access to the library is attempted. The write lock file is deleted when access is completed; the read lock file is not. Also, the library is marked so that it knows to use external locking. Use the -i option to clear the external locking mark in the library, so that it will henceforth use internal locking.

Though external locking is portable, it has two drawbacks that make internal locking the preferable choice where available. First, it tends to be slower than internal locking. Secondly, if processes die abruptly—due to signals, operator intervention, and so on—write lock files can be left hanging around, or read locks can have counts that never go to zero. This impedes further access until a recovery procedure (stop all processes, delete the lock files) is performed. With internal locking, the operating system automatically performs clean up when processes die unexpectedly.

By default, libraries are created to use internal file locking. However, if a library is created on a platform where internal locking is not available, locking defaults to external. On such platforms, attempts to set internal locking are ignored. External locking might be necessary in cross-platform network environments where the network locking facilities are inadequate. Refer to your operating system's installation notes for further information about which file locking scheme is used on your platform and/or network environment.

Marking a Library Read-only

Use of the -o option makes a library read-only. This is not a reversible operation unless the library has been compacted using the -m option.

When the read-only operation is not reversible, in order to write to a read-only library, you have to create a new library, extract the members from the read-only library, and move them into the new library. Read-only libraries generally provide quicker access.

Synchronize Library with Source Code Management

Library copies of screens can become unsynchronized with source management directories. This can happen if screens are extracted and edited directly with the source code management tool as opposed to using the screen editor interface to check screens in and out.

Run formlib with the -s option to ensure that your libraries are synchronized with the source management directory. The specified library is moved to a new library with the same name, but with a .jbl (backup library) extension, and a new library is created, having the name of the original library. Any screens that were not under source code management are copied from the backup library to the new library. Screens that were under source management, but were checked out when formlib was executed are also copied from the backup library to the new library.

All screens that are under source code management and checked-in when formlib was executed are copied from the source code management directory to the new library. In this way, you can be assured that your libraries contain the latest revisions before distributing your libraries.


jif2asc

Converts JIF between binary and ASCII format for JetNet and Oracle Tuxedo applications

jif2asc -a [-fp]  ascJIF binJIF
jif2asc -b [-fp]  ascJIF binJIF

-a
Create ASCII JIF named ascJIF from specified binary binJIF.

-b
Create binary JIF named binJIF from specified ascJIF.

-f
Overwrite an existing file.

-p
Write the output file to the directory containing the input file.

ascJIF
Name of ASCII JIF to be converted or created.

binJIF
Name of binary JIF to be converted.

Description

JetNet and Oracle Tuxedo applications require a binary JIF for execution. In the JIF editor, the JIF is saved as binary. The jif2asc command-line utility lets you convert a JIF between ASCII and binary formats.

Both input and output files must be named, there is no default naming convention. The output file is created in the current directory, unless the -p option is used to indicate that the output file is to be written in the same directory as the input file.

An attempt to overwrite an existing file without using the -f option produces an error message and no file is written.


jpl2bin

Converts JPL modules between binary and ASCII formats

jpl2bin -a [ -fpv] [ -eext ] binary ...
jpl2bin -b [ -rfpv] [ -eext ] textFile ...
jpl2bin -s binary ...

-a
Convert compiled JPL to source (default extension is *.jpl).

-b
Compile JPL from source to binary format (default extension is *.bin).

-eext
Replace the default bin extension with the specified extension ext on the binary output filename. There should be no space between the -e switch and the extension name. To omit an extension, supply a value of - (dash) for ext; i.e. -e-.

-f
Permit the output file to overwrite an existing file.

-p
Output the binary file to the same directory as input file.

-r
Exclude source from compiled binary. Useful for removing source from a production distribution. However, without the source, the module cannot be edited within the screen editor.

-s
Strip source from the compiled binary (overwrites input).

-v
List the name of each file as it is processed.

binary
Name of the compiled JPL file.

textFile
Name of the source text file.

Description

jpl2bin lets you compile JPL modules before storing them in a library or before making them memory-resident. Under UNIX, run jpl2bin from the command line; under Windows, choose the jpl2bin icon or run it from a command prompt; makefile or batch file.

Note: Panther always performs colon preprocessing at runtime; therefore, a module is fully compiled only when it executes.

jpl2bin saves the module to a file of the same name with a *.bin extension, unless you specify a different extension.


m2asc

Converts menu files between binary and ASCII formats

m2asc -a [ -fv ] [ -i  includeFile ] asciiFile menuFile [menuFile ...]
m2asc -b [ -fv ] asciiFile [asciiFile ...]

-a
Convert specified binary menu files to ASCII.

-b
Convert the specified ASCII files to binary.

-f
Overwrite an existing file.

-i includeFile
Include specified includeFile at the beginning of ASCII output.

-v
Generate a list of files as they are processed.

asciiFile
Name of ASCII file as output with -a or as input file input with -b.

menuFile
Name of binary menu file (as extracted with formlib utility).

Description

The m2asc utility lets you convert binary menu files to ASCII and vice versa. You must extract the menu file from its library with the formlib utility before using m2asc.

ASCII menu definitions define a menu as a hierarchy, where the top-level menu and its items are defined first along with global menu properties, followed by submenus and their items. Each component of a menu definition is identified by a keyword (refer to Table A-1 and, optionally, a unique name.

Table A-1 ASCII menu keywords

Menu keyword Description

ACTION

Invokes an action through a control string.

EDCLEAR

Replaces the selected text with spaces.

EDCOPY

Copies selected text to the clipboard.

EDCUT

Cuts selected text to the clipboard.

EDDEL

Deletes the selected text.

EDPASTE

Pastes the clipboard contents.

EDSELECT

Selects the current widget's contents.

FILE

Source file of the menu script. You can write multiple menu scripts to the same ASCII text file; each script begins with a FILE:script-name identifier. When m2asc converts the ASCII file to binary format, each script is saved to its own file.

MENU

Starts a menu or submenu definition. All keywords that follow MENU identify the menu's items.

SEP

Draws a separator between the previous and next menu items.

SUBMENU

Invokes another menu. If the SUBMENU item is on the menu bar, the submenu displays as a pulldown; otherwise, the submenu displays to its right.

TOGGLE

Invokes an action through a control string and toggles the indicator on or off.

WINLIST

Identifies the item as a menu that lists all open windows.

WINOP

Identifies the item as the windows menu of the current plat form—for example, under Windows, the Windows menu with Arrange Icons, Tile, and Cascade. Applications running in character-mode ignore this item.

Each menu and menu item definition has properties; these properties are specified immediately below the component's identifier. For example, the following statements define a submenu item myoption: its label is Options with a keyboard mnemonic of O; it invokes the menu myoptionsub; and it is initially available for selection (ACTIVE=YES):

SUBMENU:myoption
LABEL=&Options
SUBMENU=myoptionsub
ACTIVE=YES

Refer to Table 15-1 for a list of menu-specific properties.

Example

The following menu script is the ASCII output of a truncated version of the menu bar used by Panther's screen editor. The example includes two of the main menu options and their associated submenus: File and Help.

FILE:semain

MENU:sm_se_main_menu
ACTIVE=YES
INDICATOR=NO
SHOW-ACCEL=YES
ACCEL-ACTIVE=YES
SUBMENU:sm_se_file
LABEL=&File
SUBMENU=sm_se_file_menu
EXT-HELP-TAG=basicFilemenu
STAT-TEXT=File Operations
SUBMENU:sm_se_help
LABEL=&Help
SUBMENU=sm_se_help_menu
IS-HELP=YES
STAT-TEXT=Get Help!
MENU:sm_se_file_menu
TEAR=NO
EXTERNAL=NO
ACTIVE=YES
INDICATOR=NO
SHOW-ACCEL=YES
SEP-STYLE=SINGLE
SUBMENU:sm_se_new
LABEL=&New
SUBMENU=sm_se_new_menu
IS-HELP=NO
EXT-HELP-TAG=FileNew
STAT-TEXT=Create new screen
SUBMENU:sm_se_open
LABEL=&Open
SUBMENU=sm_se_open_menu
IS-HELP=NO
EXT-HELP-TAG=FileOpen
STAT-TEXT=Open existing screen
ACTION:sm_se_save
LABEL=&Save
CONTROL=^jm_keys PF5
ACTIVE=YES
IS-HELP=NO
EXT-HELP-TAG=FileSave
ACCEL=PF5
ACCEL-ACTIVE=NO
SHOW-ACCEL=YES
DISPLAY-ON=BOTH
STAT-TEXT=Saves the current screen
ORDER=18
ACTIVE-PIXMAP=save-act
INACTIVE-PIXMAP=save-dis
TOOL-TIP=Save
ACTION:sm_se_set_test
LABEL=&Test Mode
CONTROL=^jm_keys PF2
IS-HELP=NO
EXT-HELP-TAG=FileTestMode
ACCEL=PF2
ACCEL-ACTIVE=NO
SHOW-ACCEL=YES
DISPLAY-ON=BOTH
STAT-TEXT=Switch to Test Mode
ORDER=19
ACTIVE-PIXMAP=test-act
TOOL-TIP=Test Mode
SEP:sm_se_file_sep2
SEP-STYLE=SINGLE
ACTION:sm_se_exit
LABEL=E&xit
CONTROL=^jm_keys CLAPP
ACCEL=CLAPP
IS-HELP=NO
EXT-HELP-TAG=FileExit
ACCEL-ACTIVE=NO
SHOW-ACCEL=YES
STAT-TEXT=Exit the editor
MENU:sm_se_new_menu
TEAR=NO
EXTERNAL=NO
ACTIVE=YES
INDICATOR=NO
SHOW-ACCEL=YES
SEP-STYLE=SINGLE
ACTION:sm_se_new_screen
LABEL=&Screen
CONTROL=^filemenu new screen
IS-HELP=NO
EXT-HELP-TAG=FileNew
SHOW-ACCEL=YES
DISPLAY-ON=BOTH
STAT-TEXT=Creates new untitled screen
ORDER=11
ACTIVE-PIXMAP=new-act
INACTIVE-PIXMAP=new-dis
TOOL-TIP=New Screen
ACTION:sm_se_new_jpl
LABEL=&JPL
CONTROL=^filemenu new jpl
IS-HELP=NO
EXT-HELP-TAG=FileNew
SHOW-ACCEL=YES
STAT-TEXT=Creates new jpl
ACTION:sm_se_new_dd_entry
LABEL=Repository &Entry...
CONTROL=^filemenu new ddentry
IS-HELP=NO
EXT-HELP-TAG=FileNew
SHOW-ACCEL=YES
STAT-TEXT=Create new repository entry
ACTION:sm_se_new_lib
LABEL=&Library...
CONTROL=^filemenu new lib
IS-HELP=NO
EXT-HELP-TAG=FileNew
SHOW-ACCEL=YES
STAT-TEXT=Create a new library
MENU:sm_se_open_menu
TEAR=NO
EXTERNAL=NO
ACTIVE=YES
INDICATOR=NO
SHOW-ACCEL=YES
SEP-STYLE=SINGLE
ACTION:sm_se_op_lib
LABEL=&Library...
CONTROL=^filemenu open lib
IS-HELP=NO
EXT-HELP-TAG=FileOpen
SHOW-ACCEL=YES
STAT-TEXT=Open library
ACTION:sm_se_op_db
LABEL=D&atabase...
CONTROL=^dm_handle_connect 1
ACTIVE=NO
IS-HELP=NO
EXT-HELP-TAG=FileOpen
SHOW-ACCEL=YES
STAT-TEXT=Open database
MENU:sm_se_help_menu
TEAR=NO
EXTERNAL=NO
ACTIVE=YES
INDICATOR=NO
SHOW-ACCEL=YES
SEP-STYLE=SINGLE
ACTION:sm_se_hl_topic
LABEL=Current &Topic ...
CONTROL=^jm_keys HELP
IS-HELP=NO
STAT-TEXT=Shows help on what you're doing
ORDER=191
DISPLAY-ON=BOTH
ACTIVE-PIXMAP=help-act
INACTIVE-PIXMAP=help-dis
TOOL-TIP=Help
SEP:sm_se_hl_sep1
SEP-STYLE=SINGLE
ORDER=190
DISPLAY-ON=BOTH
ACTION:sm_se_hl_about
LABEL=&About Panther ...
CONTROL=^sm_message_box( \
"Panther Version 5.5%NCopyright 1994-2016%NProlifics Inc.", \
"About Panther",0,"")
STAT-TEXT=Tells about this version of Panther

msg2bin

Converts ASCII message files to binary format

msg2bin [-pv] [-e ext] msgFile...
msg2bin [-pv] [-o file] msgFile...

-e ext
Replace default bin extension on the output file with the given extension (ext). If the -o option is used, -e is ignored.

-o file
Output is placed in a single specified file. Use this option to concatenate your user messages to Panther-messages in a single binary file. This option will overwrite an existing binary message file of the same name.

-p
Place each binary output file in the same directory as the corresponding input file.

-v
List the name of each input message file as it is processed.

msgFile
Name of ASCII file containing named messages. More than one input file can be specified.

Description

msg2bin converts ASCII message files to a binary format for use by Panther library functions. The output of msg2bin is a binary file; the utility uses the TAGs to distinguish between system and user messages. It numbers user-defined messages consecutively starting with the class number times 0x1000 (see page 45-7 for more about defining user message classes). If no classes are defined, user-defined messages are automatically numbered consecutively starting from zero; the definitions of system messages are taken from smerror.h. Be sure to maintain the order of messages and the assignment of their identifiers. Use these identifiers in the application programs to select the desired messages at runtime. Then recompile and link any non-JPL source that includes any files that contain newly defined messages.

Errors

The following table describes possible errors, their cause, and the corrective action to take:

At least one file name is required.

Cause

No message file was specified.

Action

Specify the name of the message file.

Error in %s line %d: bad tag %s
Warning in %s line %d: bad tag %s

Cause

The tag is missing or does not consist entirely of letters, digits and/or underscores. An output file will be created and RET_SUCCESS will be returned if warnings are encountered but no errors.

Action

Fix the offending tag and rerun msg2bin. Refer to smerror.h for a list of tags.

Error in %s line %d: duplicate message tag %s
Warning in %s line %d: duplicatemessage tag %s

Cause

An earlier line also contained the same system message tag. The current line is skipped. An output file will be created and RET_SUCCESS will be returned if warnings are encountered but no errors.

Action

Fix the offending line and rerun msg2bin.

Error in %s line %d: duplicate user section class %s
Warning in %s line %d:duplicate user section class %s

Cause

The user section or two letter prefix on a class indicator line is already in use. Class zero is implicitly used if a user message is encountered before any class indicator lines. An output file will be created and RET_SUCCESS will be returned if warnings are encountered but no errors.

Action

Fix the offending line and rerun msg2bin.

Error in %s line %d: invalid user message class indicator line %s
Warning in %sline %d: invalid user message class indicator line %s

Cause

A user class indicator line (which is used to start a new message User Section) is defective. The programs assume that any tag starting with a double quote is one of these. The tag must be a double quote followed by two character alphanumeric code and a double quote. The class indicator must be a digit between 0 and 7. An output file will be created and RET_SUCCESS will be returned if warnings are encountered but no errors.

Action

Fix the offending line and rerun msg2bin..

Error in %s line %d: message tag exceeds 80 characters %s
Warning in %s line%d: message tag exceeds 80 characters %s

Cause

Message name too long.

Action

Shorten the message name and rerun msg2bin.

Error in %s line %d: missing final quote &s
Warning in %s line %d: missing final quote &s

Cause

The message content starts with a quote character ( " , ', \Q ) but does not contain a matching terminal quote character. An output file will be created and RET_SUCCESS will be returned if warnings are encountered but no errors.

Action

Fix the offending message and rerun msg2bin.

Error in %s line %d: text after final quote %s
Warning in %s line %d: text after final quote %s

Cause

The message content starts with a quote character ( " , ', \Q ) but there are characters after the matching terminal quote character. Perhaps a backslash is missing. An output file will be created and RET_SUCCESS will be returned if warnings are encountered but no errors.

Action

Fix the offending line and rerun msg2bin.

Error processing file %s

Cause

An error was encountered reading or writing the file.

Action

Confirm that the file is available and that the target directory can be written.

File '%s' not found.

Cause

An input file was missing or unreadable.

Action

Check the spelling, presence, and permissions of the file in question.

Insufficient memory available.

Cause

The utility could not allocate enough memory for its needs.

Action

None.

Invalid character(s) in -x option.

Cause

The -x option (characters to prefix to the tag) starts with a digit or contain a character that is not an alphanumeric or an underscore.

Action

Specify a valid prefix and rerun msg2bin.

Line too long: %s

Cause

The message has exceeded 1024 characters.

Action

Split the message into two separate messages or edit the message length.

Message tag exceeds 80 characters:%s

Cause

Message name too long.

Action

Shorten the message name and rerun msg2bin.

Missing '=' in line: %s

Cause

The line in the message had no equal sign following the tag.

Action

Correct the input and rerun msg2bin.

Warning in %s line %d: message tag exceeds 31 characters %s

Cause

The tag is longer than 31 characters but is shorter than 80.

Action

None.

Warning in %s line %d: prefix does not match user section class %s

Cause

The first two characters of a user message do not match the two characters specified in the most recent user message class indicator line. An output file will be created and RET_SUCCESS will be returned if warnings are encountered but no errors.

Action

Fix the offending tag and rerun msg2bin.

Warning: no messages in user section \"%.2s\"

Cause

The input file had a user message class indicator line that did not have any user messages after it. That section will not be included in the output file.

Action

Remove the offending class indicator and rerun :msg2bin.


msg2hdr

Creates header files for user messages

msg2hdr [-dfjpv] [-n num] [-s pfix] [-x pfix] [-o file] [-e ext] msgFile...

-d
Decimal base in the output header file. Default is base 16 (hexadecimal).

-e ext
Replace default extension (h or jpl) on the output file with the specified extension ext.

-f
Output file may overwrite an existing file.

-j
Create a JPL global variable file from msgFile.

-n num
Start numbering messages with the specified num for the first #define or global. If no number is entered, 0 (zero) is used.

-o file
Direct output to the named file.

-p
Place output file in the same directory as the corresponding input file.

-s pfix
Select only message names beginning with the specified prefix pfix.

-v
Generate list of the files processed.

-x pfix
Prepend the specified prefix pfix to the tag portion of the message.

msgFile
Name of ASCII file containing your application's messages.

Description

msg2hdr converts an ASCII message file that contains your application's messages to a C header file. The output of msg2hdr is a .h file with #define statements for each user message tag. The messages are numbered sequentially starting with 0x0 to 0xF. The message portion is copied to the header file as a comment.

For example, a user message file with multiple sections might look like this:

"U0" = 0
U0_BADVAL = Bad value
U0_WRONGDATE = Date must be within 30 days of current date
"U1" = 1
WRONGRATE = This is not the applicable rate

This yields the following output:

#define U0_BADVAL      0x0     /* Bad value             */
#define UO_WRONGDATE 0x1 /* Date must be within 30 \
> days of current date */
#define WRONGRATE 0x1000 /* This is not the \
> applicable rate */
If you use the -j option, msg2hdr yields this output:
global U0_BADVAL(1)    = 0     /* Bad value             */
global U0_WRONGDATE(1) = 1 /* Date must be within 30 \
> days of current date */
global WRONGRATE(4) = 4096 /* This is not the \
> applicable rate */

Errors

The following table describes possible errors, their causes, and the corrective action to take:

At least one file name is required.

Cause

No message file was specified.

Action

Specify the name of the message file.

Error in %s line %d: bad tag %s
Warning in %s line %d: bad tag %s

Cause

The tag is missing or does not consist entirely of letters, digits and/or underscores. It can also indicate the first character of the tag is a digit. An output file will be created and RET_SUCCESS will be returned if warnings are encountered but no errors.

Action

Fix the offending tag and rerun msg2hdr. Refer to smerror.h for a list of tags.

Error in %s line %d: duplicate message tag %s
Warning in %s line %d: duplicatemessage tag %s

Cause

An earlier line also contained the same system message tag. An output file will be created and RET_SUCCESS will be returned if warnings are encountered but no errors.

Action

Fix the offending tag and rerun msg2hdr.

Error in %s line %d: duplicate user section class %s
Warning in %s line %d:duplicate user section class %s

Cause

The user section or two letter prefix on a class indicator line is already in use. An output file will be created and RET_SUCCESS will be returned if warnings are encountered but no errors.

Action

Fix the offending line and rerun msg2hdr.

Error in %s line %d: invalid user message class indicator line %s
Warning in %sline %d: invalid user message class indicator line %s

Cause

A user class indicator line (which is used to start a new message User Section) is defective. The programs assume that any tag starting with a double quote is one of these. The tag must be a double quote followed by two character alphanumeric code and a double quote. The class indicator must be a digit between 0 and 7. An output file will be created and RET_SUCCESS will be returned if warnings are encountered but no errors.

Action

Fix the offending line and rerun msg2hdr.

Error in %s line %d: message tag exceeds 80 characters %s
Warning in %s line%d: message tag exceeds 80 characters %s

Cause

The message name (tag) is longer than 80 characters.

Action

Shorten the message name and rerun msg2hdr.

Error in %s line %d: message tag exceeds 31 characters %s
Warning in %s line %d: message tag exceeds 31 characters %s

Cause

The tag is longer than 31 characters but is shorter than 80. This causes an error if the -j (JPL) option is selected, otherwise it causes a warning. An output file will be created and RET_SUCCESS will be returned if warnings are encountered but no errors.

Action

Fix the offending tag and rerun msg2hdr.

Error in %s line %d: prefix does not match user section class
Warning in %s line %d: prefix does not match user section class %s

Cause

The first two characters of a user message do not match the two characters specified in the most recent user message class indicator line. An output file will be created and RET_SUCCESS will be returned if warnings are encountered but no errors.

Action

Fix the offending tag and rerun msg2hdr.

Error processing file %s

Cause

An error was encountered reading or writing the file.

Action

Confirm that the file is available and that the target directory can be written.

Exactly one message file name is required.

Cause

More than one input message file was specified.

Action

Run msg2hdr separately for each message file. Consider using the -n option on the subsequent messages to number the messages consecutively.

File '%s' already exists; use '-f' to overwrite.

Cause

An output file of the same name already exists.

Action

Use the -o option to specify a different output name or use the -f option to overwrite the existing header file.

If no number is entered, 0 will be used.

Cause

You did not provide a number with the -n option and it defaulted to zero.

Action

Rerun msg2hdr providing a number.

Insufficient memory available.

Cause

The utility could not allocate enough memory for its needs.

Action

None.

Invalid all-numeric message name '%s'

Cause

At least one non-numeric character must be in a message name.

Action

Rename the offending message and rerun msg2hdr. (If you have already converted the message file to binary, you will need to rerun msg2bin.)

Invalid character(s) in -x option.

Cause

The -x option (characters to prefix to the tag) starts with a digit or contain a character that is not an alphanumeric or an underscore.

Action

Specify a valid prefix and rerun msg2hdr.

Missing '=' in line: %s

Cause

The line in the message had no equal sign following the tag.

Action

Correct the input and rerun msg2hdr. (If you have already converted the message file to binary, you will need to rerun msg2bin.)

Missing message name for '%s'

Cause

The message had no characters before the equal sign.

Action

Provide a name for the offending message and rerun msg2hdr. (If you have already converted the message file to binary, you will need to rerun msg2bin.)

Warning: no messages in user section \"%.2s\"

Cause

The input file had a user message class indicator line that did not have any user messages after it.

Action

Remove the offending class indicator and rerun msg2hdr.


s2asc

Converts styles files between binary and ASCII formats

s2asc -a [-f] asciiFile styles.sty
s2asc -b [-f] asciiFile

-a
Create ASCII listing of styles.sty. The styles file must be named styles.sty.

-b
Create a binary style file from an ASCII listing. The name of the binary file corresponds to the name specified in the s:name option in the ASCII file. To have this binary file accessed by your application, change the name of the file to styles.sty.

-f
Overwrite an existing styles.sty file.

asciiFile
With the -a option, name of the file in which to place the ASCII styles settings. With the -b option, name of the file containing ASCII text for conversion to binary format.

Description

The s2asc utility must be executed from the command line. With the utility, you can convert your styles.sty file between binary and ASCII format. After converting an ASCII file to binary with s2asc, use formlib to put it in the appropriate library. You might do this in order to place the file under source control management or to document or review the contents of the file.

The text files generated by s2asc contain a list of the property settings for each style, followed by a list of the styles assigned to each class.