Outputting Error Messages (ERROR)

The ERROR command outputs a diagnostic message to the listing file. Two forms of ERROR command syntax are available, to output user-defined and standard error messages, as follows:

$\textbf{ERROR / } \mathit{severity}, \,\mathit{format\_string} \;{\small \sim}\!\big[,\mathit{expression}\,\big]$

$\textbf{ERROR / } \mathit{errnum} \;{\small \sim}\!\big[,\mathit{expression}\,\big]$

The “severity” form of the ERROR command is used to output a user defined error. The diagnostic message severity must be a whole number in the range 0-99, where by standard convention: 0 is a message, 4 a warning, 8 an error and 16 a severe error. The diagnostic message text follows the severity. See the “Output String Format” for a description of how the string to be written is constructed using the format_string argument.

For example:

ERROR/0,'Pallet change'
ERROR/4,'Cannot determine diameter of tool !(\*)',$T

The “errnum” form of the ERROR command is used to output standard error diagnostics. The diagnostic error number must be a whole number greater than 99, matching one of the standard diagnostics found in the pos260.err file (see “Error File”). Some standard diagnostics include “!(…)” output string format descriptors. The ERROR command must include a text or numeric expression (as appropriate) for each such descriptor.

ERROR/1302020
ERROR/1300001,'PALLET'

Calling other programs (SYSTEM)

The SYSTEM command is used to spawn processes from within the post-processor. The SYSTEM command allows the macro processor to run another program or issue an operating system command from within a macro. The command takes the form:

$\textbf{SYSTEM / } \mathtt{'}string \,\mathtt{'}$

The command defined within the string is sent to the Windows command shell, relative to the current working directory. If the command name and/or file name specifications contain embedded blanks, they must be enclosed in quotes as they would if typed in the command shell. Executable files in the File Storage section can be run using an “//ICAMFS/” path for the file name.

The $ERRNO system variable contains the status code returned by the operating system when control was returned to the macro processor.

CL File I/O from a Macro

The macro language provides the ability to reposition the input CL file pointer, read CL records from the input CL file, modify the last CL record read and process the last CL record read. The “last CL record read” is updated each time a macro TAPERD command is executed and each time that a CL record is read in the normal course of processing the input CL file.

Repositioning the CL File (SEARCH)

The SEARCH macro command requires a single numeric expression specifying a record number as its argument. It repositions the input CL file so that the next CL record read will be at the given position.

$\textbf{SEARCH / } \mathit{record\_number}$

The SEARCH macro command is frequently used in conjunction with the $FCLREC() function, as illustrated in the following example:

$$ save the next CL record position in a local variable
%L01=$FCLREC()+1
$$ do some processing using TAPERD, SEARCH or TAPEWT
…
…
$$ reset the CL file record pointer when finished
SEARCH/%L01

Reading a CL Record (TAPERD)

The TAPERD macro command is used to read the next CL record from the input CL file.

$\textbf{TAPERD}$

The TAPERD command takes no arguments.

Functions to Examine the Last CL Record

The following functions provide information about the last CL record read:

Function

Value

$FEOF( )

$TRUE if CL record is FINI

$FCLREC( )

record number of CL record

$FCLASS( )

numeric class of CL record

$FSUBCL( )

numeric subclass of CL record

$FSIZE( )

number of arguments in CL record

$FCL(i)

ith argument of CL record

$FCLS(i,j)

sequence of arguments i through j of CL record

The expression $FEOF() has the same value as “$FCLASS().EQ.14000”. Note that the $FEOF function serves a dual purpose in that it can also be used to determine the end-of-file status of a file opened with the OPEN macro command.

The $FCLASS and $FSUBCL functions can be particularly useful when dealing with wildcard macros. They can indicate the original input record class and subclass of the record that matched the wildcard macro.

More detailed descriptions of these functions can be found in “CL Data Parsing Functions”.

Modifying the Last CL Record (CLPUT)

The CLPUT macro command is used to modify one or more elements of the last CL record read, although the modifications are not acted upon until a TAPEWT command is coded. The first CLPUT argument specifies the index of the first element of the input CL record to be modified, followed by one or more argument values to be put starting at that location. An index value of –1 refers to the ISO W2 (class) position. An index value of “0” refers to the ISO W3 (subclass) position. Index values of “1” or greater refer to ISO positions W4 and onwards. For example, if the last CL record read was SPINDL/300,IPM, the command:

CLPUT/1,200

would change the record to SPINDL/200,IPM the command:

CLPUT/1,200,RPM

would change the record to SPINDL/200,RPM.

A $NULL value can be used to delete CL elements from the given location onwards. This can only be done from element 1 (W4) onwards. For example, if the major word code of AIR is 1011 and the current CL record is SPINDL/300,RPM, the command:

CLPUT/-1,2000,1011,ON,$NULL

would change the record to AIR/ON. Note that the above command is equivalent to the following four commands given in any order:

CLPUT/-1,2000
CLPUT/0,1011
CLPUT/1,ON
CLPUT/2,$NULL

Processing the Last CL Record (TAPEWT)

The TAPEWT macro command is used to process the last CL record read from the input CL file, as modified by CLPUT commands if any.

$\textbf{TAPEWT}$

The TAPEWT command takes no arguments. If macro matching is not disabled, the processor will try to match the record against a user-defined macro.

Deleting CL File Records (TAPEOP)

The TAPEOP command allows the user to delete single records and ranges of records from the CL File. The syntax is as follows:

$\textbf{TAPEOF / DELETE } {\small \sim}\!\begin{pmatrix},\mathit{cln} \begin{bmatrix},\textbf{THRU}, \begin{pmatrix}\begin{array}{l}\mathit{cln} \\ \textbf{ALL} \end{array}\end{pmatrix}\end{bmatrix}\end{pmatrix}$

One or more individual records can be deleted by specifying the CL record number cln. A range of records can be deleted by coding cln,THRU,cln. The keyword ALL can be specified instead of the ending CL record number to delete all records to the end of the CL file.

This command is useful if you have already read ahead in the CL file to get a specific record and have processed it using the TAPEWT function. The use of the TAPEOP command will prevent the “gotten” record from being reprocessed the next time it is read. The following example reads ahead in the CL file, gets the next spindle command, outputs it and then deletes it from the CL file so that it will not be processed again the next time it is read:

%L01=$FGET(SPINDL)
TAPEWT
TAPEOP/DELETE,%L01

Another available format of the TAPEOP command is:

$\textbf{TAPEOP / DELETE},\textbf{CLEAR}$

The CLEAR option clears the deletion table. This may be necessary if a large number of TAPEOP/ DELETE commands are issued. The record numbers are stored in a buffer area. The CLEAR option can be used to remove any previous record numbers from that buffer area.

CL File Processing Examples

The following macro positions the CL file to the end-of-file.

WHILE/.NOT.$FEOF()
  TAPERD
ENDOF/WHILE

The following macro code counts the number of post-processor commands in the input CL file. The CL file pointer is reset at the end:

K=$FCLREC()
SEARCH/1
TAPERD
I=0
WHILE/.NOT.$FEOF()
  IF/$FCLASS().EQ.2000
    I=I+1
  ENDOF/IF
  TAPERD
ENDOF/WHILE
PPRINT/'!(s9) pp commands found ',I
SEARCH/K+1

The following macro code stores in %L23 the value coded after the minor word RANGE in the current CL record. If there is no RANGE minor word, %L23 will have $NULL value after the loop:

%L23=$NULL
DO/%L00=1,$FSIZE()
  IF/$FCL(%L00).EQ.RANGE
    %L23=$FCL(%L00+1)
    EXIT/1
  ENDOF/IF
ENDOF/DO

The exact same results could be achieved using the $FGETARG function, as follows:

%L23=$FGETARG(RANGE)

Text File I/O from a Macro

The macro language provides the ability to read from and write to external text files. These files are connected to and disconnected from the macro processor using OPEN and CLOSE commands. Input and output to external files is done using the READ and WRITE commands.

When a file is opened, it must be assigned a “unit” number. This is a number that for historical purposes must range from 20 through 29. This unit number will then be used in subsequent READ, WRITE and CLOSE statements to identify the particular file opened. In this way more than one file can be processed simultaneously.

If an error occurs during text file I/O, a diagnostic message will be output and the macro will terminate. Coding PPFUN/21,ON changes the default to allow macros to continue after an I/O error. The error return code will be stored in the $ERRNO macro system variable (see “Error Message Variables”). Macros must test for I/O errors and act accordingly since GENER will not output any message to indicate an I/O failure. The PPFUN/21 command is modal and is OFF by default.

Text file I/O processing can optionally be monitored in the GENER Console trace window for debugging purposes. Tracing of I/O is off by default. Tracing is controlled from the GENER full display Tools»Preferences»Trace menu “Macro IO commands” check box.

Opening a Text File (OPEN)

The OPEN command opens a text file with a given name on a given unit. The file name is optional if the unit is pre-connected. If FRONT is specified, the unit is rewound. If REAR is specified, the unit is positioned at the end-of-file. FRONT is the default. The OPEN command has the following syntax:

$\textbf{OPEN / } \mathit{unit} \begin{bmatrix} ,\! \begin{array}{l} \textbf{FRONT} \\ \textbf{REAR} \end{array}\,\end{bmatrix} \big[,\mathit{filename}\,\big]$

Two special file names are predefined to permit input and output to the console; they are STDIN and STDOUT.

Closing a Text File (CLOSE)

The CLOSE command closes a text file. It has the following syntax:

$\textbf{CLOSE / } \mathit{unit}$

It is good programming practice to close files when finished using them.

Writing to a Text File (WRITE)

The WRITE command writes a string into a text file. The syntax of the WRITE command is:

$\textbf{WRITE / } \mathit{unit}, \;\mathit{format\_string} \;{\small \sim}\!\big[,\mathit{expression}\,\big]$

See “Output String Format” for a description of how the string to be written is constructed using the format_string argument.

Normally, a file must be opened before a write operation is attempted. This is true for units 20 through 29. All other units may be written to but may not be opened or read from. It is important to exercise caution when writing to units outside of the safe range (20 to 29). This is especially important when considering the database files. These files are binary format and an inadvertent write could corrupt your database. We suggest that only unit 10, the back plot file, be written to. All other writes should be output to units 20 through 29.

Reading from a Text File (READ)

The READ command can be used to read a line from a text file into one or more macro variables. The text file must be open when the READ is executed. The syntax of the READ from text file command is:

$\textbf{READ / } \mathit{unit} \begin{bmatrix} ,\! \begin{array}{l} \textbf{INCR }\\ \textbf{DECR} \end{array}\,\end{bmatrix} ,\mathit{format\_string} \; {\small \sim}\!\big(,\mathit{variable\_name}\,\big)$

If INCR is specified, the next line is read. This is the default. A READ using INCR should only be performed if “$FEOF(unit)” returns false. If DECR is specified, the last line is read again. If no lines have been read yet, the first line is read.

See “Input String Format” for a description of how the variables in the input list are assigned values from the input text using the format_string.

Reading from a String Value (READ)

The READ command can also be used to do an “internal read” from a string value. The syntax of the internal READ command is:

$\textbf{READ / } \mathit{source\_string} , \;\mathit{format\_string} \; {\small \sim}\!\big(,\mathit{variable\_name}\,\big)$

See “Input String Format” for a description of how the variables in the input list are assigned values from the input string variable source_string using the format_string.