$SCANTAB – Create a scan table

Format description

The following format descriptions apply:

Boundary form


>>-+--------+--$SCANTAB----------------------------------------->
   '-symbol-'             

>--TABLE--=--+-+---+--HASP--+------------+--+---+-+------------><
             | '-(-'        '-,--NOENTRY-'  '-)-' |   
             +-+---+--USER--+------------+--+---+-+   
             | '-(-'        '-,--NOENTRY-'  '-)-' |   
             +-END--------------------------------+   
             '-(DYNAMIC,pair-offset)--------------'

Entry form


>>-+--------+--$SCANTAB--NAME--=--char-name--------------------->
   '-symbol-'                                 

>--+----------------------------+------------------------------->
   '-,--CONV--=--+-LONG-------+-'   
                 +-NUM--xxxx--+     
                 +-HEX--------+     
                 +-CHAR--xxxx-+     
                 +-STCK--xxx--+     
                 +-FLAG-------+     
                 +-ALIAS------+     
                 +-VECTOR-----+     
                 '-SUBSCAN----'     

>--+------------------------------------------+----------------->
   '-,--CB--=--+-HCCT-----------------------+-'   
               +-DTE------------------------+     
               +-+-TOKEN,-----------------+-+     
               | +-name-------------------+ |     
               | +-TOKEN,--name--,HOME----+ |     
               | +-TOKEN,--name--,PRIMARY-+ |     
               | +-TOKEN,--name--,SYSTEM--+ |     
               | '-TOKEN,--name--,SUBSYS--' |     
               +-HCT------------------------+     
               +-PCE------------------------+     
               +-DCT------------------------+     
               +-UCT------------------------+     
               +-(--TEMP--,--size--)--------+     
               +-PARENT---------------------+     
               '-PRESCAN--------------------'     

>--+----------------------+------------------------------------->
   |             .-FAIL-. |   
   '-,--NOCB--=--+-SKIP-+-'   

>--+----------------------------------------------------------------------------------+-->
   '-,--CBIND--=--(--field-name1--,--dsect1--,--instruction1--,--field-name2--,--…--)-'   

>--+-----------------------------+--+---------------------+----->
   '-,--CLEANUP--=--routine-name-'  '-,--CMDRDIR--=--cccc-'   

>--+---------------------------+--+-------------------------+--->
   '-,--COMAUTH--=--+-JOB----+-'  '-,--COMENT--=--qualifier-'   
                    +-SYSTEM-+                                  
                    '-DEVICE-'                                  

>--+------------------------+--+----------------------+--------->
   '-,--COMPMSG--=--+-YES-+-'  '-,--COMREJ--=--REMOTE-'   
                    '-NO--'                               

>--+----------------------------+------------------------------->
   '-,--DELTEXT--=--+-DEFAULT-+-'   
                    '-NONE----'     

>--+-----------------------------+--+-----------------------+--->
   '-,--DISPALL--=--+-YES------+-'  '-,--FILTER--=--+-YES-+-'   
                    +-NO-------+                    '-NO--'     
                    +-LONGONLY-+                                
                    '-NOTLONG--'                                

>--+----------------------------------------------------+------->
   '-SUBFLD--=--(--field--,--controlblock--,--length--)-'   

>--+----------------------------------------------------------------------+-->
   '-,--SUBSCRP--=--+---+--+-low-val--,--high-val--+-,--HCT-+----+--+---+-'   
                    '-(-'  |                       '-,--UCT-'    |  '-)-'     
                           '-low--,--high--,--length--+-,--HCT-+-'            
                                                      '-,--UCT-'              

>--+------------------------------------------------------+----->
   '-,--FIELD--=--+---+--field-name--+-----------+--+---+-'   
                  '-(-'              '-,--length-'  '-)-'     

>--+-------------------------+---------------------------------->
   '-,--DSECT--=--dsect-name-'   

>--+------------------------------+----------------------------->
   '-,--RANGE--=--(--v1--,--v2--)-'   

>--+---------------------------+--+----------------------+------>
   '-,--RELATED--=--entry-list-'  '-,--SSOPT--=--+-YES-+-'   
                                                 '-NO--'     

>--+------------------------------------------------------------------------+-->
   '-,--VALUE--=--(--v1--,--f1v1--,--f2v1--,--v2--,--f1v2--,--f2v2--,--…--)-'   

>--+--------------------------------------+--------------------->
   '-,--CALLERS--=--(--v1--,--v2--,--…--)-'   

>--+------------------------------------------------------------------------+-->
   '-,--PRESCAN--=--+---+--routine-name--,--+-------------------+--+------+-'   
                    '-(-'                   '-+-SET-----+--)--…-'  '-,--…-'     
                                              +-DISPLAY-+                       
                                              +-FILTER--+                       
                                              '-DELETE--'                       

>--+-----------------------------+------------------------------>
   '-,--PSTSCAN--=--routine-name-'   

>--+------------------------------------------------------+----->
   |                                   .-,--MCT--.        |   
   '-,--SCANTAB--=--+---+--table-name--+-,--UCT--+--+---+-'   
                    '-(-'              +-,--ADDR-+  '-)-'     
                                       '-,--VCON-'            

>--+---------------------------------------------------------------------+-->
   |                      .-1-.                                          |   
   '-,--VCOUNT--=--+---+--+---+--nnn--+-----------+--+----------+--+---+-'   
                   '-(-'              '-,--IGNORE-'  '-vol-size-'  '-)-'     

>--+---------------------------+-------------------------------->
   |            .-NO--.        |   
   '-,--OBS--=--+-YES-+--+---+-'   
                         '-)-'     

>--+-----------------------------------+------------------------>
   |               .-keyword-len-----. |   
   '-,--MINLEN--=--+-min-keyword-len-+-'   

>--+------------------+--+------------------------+------------->
   '-,--MSGID--=--nnn-'  '-,--DISPKEY--=--+-YES-+-'   
                                          '-NO--'     

>--+-----------------------------+--+----------------------+---->
   '-,--TEXT--=--'--ccc--…--c--'-'  '-,--TOKEN--=--cb-addr-'   

>--+------------------------+----------------------------------->
   '-,--DISPLAY--=--+-YES-+-'   
                    '-NO--'     

>--+------------------------------------+----------------------->
   |             .-NO-----------------. |   
   '-,--CRLF--=--+-(--YES--+-,C--+--)-+-'   
                           +-,L--+          
                           +-,D--+          
                           +-,DE-+          
                           '-,E--'          

>--+------------------------------------------------------+----->
   '-,--ROUT--=--+---+--rout-cde1--+--------------------+-'   
                 '-(-'             '-…--,--rout-cden--)-'     

>--+------------------------------------------------------+----->
   '-,--DESC--=--+---+--desc-cde1--+--------------------+-'   
                 '-(-'             '-…--,--desc-cden--)-'     

>--+------------------------+--+---------------------+---------->
   |                .-NO--. |  '-,--DISPERS--=--R--n-'   
   '-,--JESROUT--=--+-YES-+-'                            

>--+-----------------------------+------------------------------>
   |                .-BOTH-----. |   
   '-,--ACTDISP--=--+-ACTIVE---+-'   
                    '-INACTIVE-'     

>--+--------------------------+--------------------------------->
   '-,--ACTFLAG--=--flag-byte-'   

>--+----------------------------+--+-----------------------+---->
   |               .-BOTH-----. |  |               .-YES-. |   
   '-,--ACTSET--=--+-ACTIVE---+-'  '-,--GENSET--=--+-NO--+-'   
                   '-INACTIVE-'                                

>--+--------------------+--+-----------------------+------------>
   '-,--LKUPFLD--=--arg-'  '-,--SCAN--=--scan-type-'   

>--+--------------------------+--+--------------------+--------->
   '-,--WARNING--=--byte-mask-'  |            .-NO--. |   
                                 '-,--JOB--=--+-YES-+-'   

>--+----------------------------------+--+------------------+--->
   '-,--FILTER_XCLUDE--=--filter-list-'  '-,--WIDTH--=--nnn-'   

>--+--------------------------+--------------------------------><
   |               .-0------. |   
   '-,--COMPCE--=--+-compce-+-'

TABLE=

Specifies the start or end of a scan table.

Specify TABLE=HASP or TABLE=USER to start the corresponding table. Optionally specify a second parameter of NOENTRY, for example, TABLE=(USER,NOENTRY)), to indicate no ENTRY statement need be generated for the label of the scan table.

DYNAMIC specifies that this is a dynamic table. The second and subsequent positionals, pair-offset, specify the offset of the $PAIR in either the MCT or UCT control block with which this table is to be associated. If the table pair in the MCT or UCT is not defined through the $PAIR macro, an assembler MNOTE will be issued.

Specify TABLE=END to terminate a scan table.

Other operands are ignored if TABLE is specified, and a label is required on the $SCANTAB macro if a table is being started. If TABLE= and NAME= are both not specified, only the mapping of an $SCANTAB entry is generated by the macro.

NAME=

Specifies a character name for the scan table entry that indicates the scan keyword being defined. For example, PRINTER, CONSOLE, or JOENUM parameter on the OUTDEF statement. If TABLE= and NAME= are both not specified, only the mapping of an $SCANTAB entry is generated by the macro.

CONV=

Specifies the conversion to do (and defines the valid input) when the keyword defined by NAME= is encountered during a scan. CONV= is required if $SCANTAB is used to generate a table entry. The following specifications are valid:

LONG

Indicates that if you also specifies DISPALL=LONGONLY on this macro call, this call will display on a DISPALL= request.

NUMxxxx

Indicates that the keyword represents a binary value. The optional second positional defines a multiple to round the input value to before storing. The optional third positional defines a value by which the value of the keyword is multiplied before storing. For example, CONV=(NUM,8,100).

The xxxx can be specified to the following values:

T: Indicates that a thousands separator (,) is used to display the numeric value. For example, 1,234 instead of 1234.
U: Indicates that the value in the field is treated as an unsigned integer.
S: Indicates that the value in the field is treated as a signed integer.
*: Indicates that an asterisk (*) is displayed when the value in the fullword numeric field is X'FFFFFFFF'.

HEX

Indicates that the keyword represents a hexadecimal value that is stored in binary. The optional second and third positionals operands are the same as CONV=NUM.

CHARxxxx

Indicates that the keyword represents a character value and defines the allowed character input. If the first positional for CONV= is CHAR, any characters not required for syntax within $SCAN are valid for the value unless a specific list of characters is provided.

CONV=CHAR will allow right and left parenthesis as input for the scan keyword defined by the $SCANTAB entry. CONV=(CHAR,x1,x2,x3,...,xn) where x1-xn are specific characters allowed to be specified for the keyword defined by the $SCANTAB entry and will allow right and left parenthesis if they are in the character list (defined by x1-xn).

The rules for coding parenthesis are as follows:

A right parenthesis will be accepted by itself
A left parenthesis, if specified, must be part of a balanced parenthesis pair.

If the first positional is CHARxxxx, for a 1- to 7-character string xxxx, the input must fall within the character sets defined by the xxxx or be one of the specific list of characters that may be optionally provided as described below.

The xxxx can be specified to the following values:

A: Indicates the alphabetic character set A-Z.
F: Indicates the first character of input must be alphabetic.
G: Indicates that the characters * and ? are valid.
H: Indicates the hexadecimal numbers 0 through 9 and characters A through F. The value will be right-justified and padded with zeros unless A, S, F, J or additional positional operands are specified.
J: Indicates the first character of input must be alphabetic or special national (JCL rules), even though the remaining input might have less strict input rules.
N: Indicates the numerics 0 through 9. The value is right-aligned and padded with zeros unless A, S, F, J or additional positional operands are specified.
R: Indicates the character data must be right-aligned rather than left-aligned.
S: Indicates the special nationals $, @, and #.
Z: Indicates the pad character is X'00'.

A specific list of allowed characters might be specified as the second, third, and so on, positional operands for CONV. They might be specified as single characters, or as 2-character hex values. The following is a valid example:

$SCANTAB  NAME=CONCHAR,  CB=HCT,  FIELD=$CCOMCHR,  CONV=(CHAR,,.,
              [,4D,+,|,50,!,$,*,¬,-,/,%,_,?,:,#,@,=,"),
              RANGE=(L'$CCOMCHR,L'$CCOMCHR),
              CALLERS=($SCIRPL,$SCIRPLC,$SCDCMDS),
              PSTSCAN=(PSTCNCHR,SET)

STCKxxx

For displays only. Indicates that the field contains a time stamp in STCK/STCKE format that should be displayed in the format (yyyy.ddd,hh:mm:ss).

The xxx indicates additional options regarding the format of the field and the display. It can be specified to the following values:

E: Indicates that the field is a STCKE not a STCK.
U: Default display but without parenthesis.
L: Indicates a Long display in the format day mon year AT hh:mm:ss.
W: Includes day of week (Long display only) dayname day mon year AT hh:mm:ss.
M: Displays time to minute precision only.
Z: Indicates that the STCK value must be converted to local time.
0,1,2,3,4,5,6: Indicates the number of decimal places of precision the second should be displayed to. This specification is not honored for 4-byte fields.
A: Indicates that the actual value to be displayed or filtered is not the time stamp itself but the difference (in seconds) between the STCK value and the current time. The same as CONV=NUM, the second and third positionals are scaling and rounding values. For example, CONV=(STCKA,,60) gives minutes.
T: Indicates that the age must be displayed with a thousands separator (,). It is used together with A.

Note: For SETs, the prescan and postscan routines are given control; otherwise, there is no effect.

FLAG[,LIST][,n]

Indicates the keyword that represents a flag value stored as the setting of one or more bits within a single flag byte. The allowed values and associated bit settings are defined by VALUE=.

LIST: An optional second positional parm to specify that JES2 should list all matching values not only the first.
n: An optional third positional parm that specifies the number of triplets in the VALUE= list that JES2 will display. (JES2 scans all other parameters for SET and FILTER calls.)

ALIAS

Indicates that the keyword is the alias of another keyword and SCANTAB= specifies the label of the scan table entry mapping that other keyword.

VECTOR

Indicates that the keyword represents a vector of values. Another level of scan is used to process the vector of values that is specified within parentheses. Therefore each value is defined positionally by another scan table that SCANTAB= points to.

SUBSCAN

Indicates that the keyword requires another level of scanning to scan suboperands. A completely recursive level of scanning is done and the keyword represents any types of suboperands that CONV= specifies. SCANTAB= specifies the address of a doubleword containing the addresses of two scan tables to pass to the recursive $SCAN call.

CB=

Specifies one of the ‘primitive’ control blocks known by $SCAN as the control block containing the fields representing the value of the keyword, or as the starting point for a control block search for that field. If a control block is not found for a keyword during a scan, and a PRESCAN routine for the keyword does not then supply the control block address, $SCAN issues a $ERROR. CB= is required if CONV= is not specified as SUBSCAN, VECTOR, or ALIAS unless PRESCAN= is specified.

HCCT

Indicates the JES2 HCCT control block.

DTE

Indicates the current daughter task element (DTE) at the time of the scan.

TOKEN,name|TOKENname,HOME| TOKENnamePRIMARY|TOKENnameSYSTEM|TOKENnameSUBSYS

Specifies the NAME associated with a name/token pair (created using the $TOKENSR service) which contains the address of the control block that contains the fields. NAMEs can be up to 16 bytes long, and must match the name specified on a $TOKENSR call. The first 4 bytes of the token are assumed to be the control block address. The remaining 12 bytes of the token are not used .

The control block address (from the token) is combined with the dsect name specified in DSECT= and field name to determine the field address. Token name on second operand of CB= is required and only allowed, if TOKEN is specified on first operand of CB= keyword.

NAME/TOKEN pairs can be created at various levels. JES2 supports tokens at the SYSTEM, TASK, or HOME level. The third operand on CB= specifies the level passed on the $TOKENSR service call. If the third operand is not specified, it defaults to TASK level.

HCT

Indicates the JES2 HCT control block.

PCE

Indicates the current processor control element (PCE) at the time of the scan.

DCT

Indicates a JES2 device control table (DCT), found by scanning all the DCTs for one whose DCTDEVN field corresponds to the NAME= specified and the device number found during the scan.

UCT

Indicates the installation-defined user control table (UCT), which is pointed to by the $UCT field of the HCT.

TEMP

Indicates a temporary control block should be allocated with a length defined by the second positional operand.

size: Indicates the length (in bytes) of the control block

If ACTFLAG is defined, $SCAN does not determine the activity level of the control block.

PARENT

Indicates the control block determined at the scan level ‘above’ this scan level should be used, i.e., when a control block is found for a CONV=SUBSCAN or CONV=VECTOR keyword, that control block is the parent control block for the resulting subscanning.

PRESCAN

Indicates the routine where the control block is located.

Attention: $SCAN does not do any searching or validating before the prescan.

If ACTFLAG is defined, $SCAN does not determine the activity level of the control block.

NOCB=

Specifies the action to take if JES2 couldn't find a control block (that is, a control block address of zero.)

FAIL: $HASP003 is issued with text REQUIRED CONTROL BLOCK(S) NOT AVAILABLE. NOCB=FAIL is the default.
SKIP: The $SCANTAB is skipped.

Note: Prescan routines, if any, locate the control block before checking for a zero value.

CBIND=

Specifies how to find the control block required for this keyword, if the primitive control block is not it. The search starts from the primitive control block address, and performs a series of operations of fields within each control block along the way. The fields used are defined by the first and second operands and the operation is defined by the third operand in each of a set of operand triplets defined to CBIND=. CBIND must be specified as a list consisting of a multiple of these three operands.

field-name1: Identifies the name of the control block field that is to be compared to the subscript name, until a match is found.
dsect1: Defines a DSECT name for the control block that contains the field.
instruction1: Defines the operation to be performed, with the current control block address, against the field.
The allowed operations are L (load), LA (load address), A (add), AH (add halfword), AL (add logical), S (subtract), SH (subtract halfword), and SL (subtract logical). If the operation specified is preceded by an asterisk (for example, *LA), then any subscript indexing for the control block search is done before this CBIND operation, rather than after all CBIND operations. Subscript indexing is defined by the SUBSCRP= operand.

CLEANUP=

Specifies routines that should be given control to clean up resources obtained by a prescan routine, even when a postscan routine does not get control (such as an $SCAN error, filter mismatch). The syntax of the keyword is:

CLEANUP=(rtn,xxx,rtn,rtn,xxx,...)

where rtn is a routine that is to be called and xxx is optional and can be one of 'HCT', 'HCCT', or 'CR11', indicating the value to be placed in register 11 on entry to the routine. Specify CR11 if the value of register 11 at the time of the $SCAN call is to be used. If none of HCT, HCCT, or CR11 is specified, then a default is used. The default depends on the location of the routine address: PADDR, UPADDR, SXADDR OR USXADDR: HCT CADDR, UCADDR: HCCT A-CON OR V-CON: HCCT in user env: CR11 otherwise.

CMDRDIR=

Specifies the response for the command is subject to redirection. The name specified (cccc) is the 4-character identifier of a redirection group which must correspond to the redirection group name (NAME=) on a $RDIRTAB macro. If the CMDRDIR parameter is not coded, the command is not subject to redirection.

COMAUTH=

Specifies the authority required to issue the specified command. Multiple authority levels may be coded for this keyword. Values allowed for this keyword are:

JOB: Job authority required.
SYSTEM: System authority required.
DEVICE: Device authority required.

COMENT=

Specifies the qualifier for command authorization. This is combined with the qualifier on the $COMTAB for the 'command verb' to provide the complete resource name. For example, if the $T command specifies 'MODIFY' as a COMENT and the $SCANTAB macro for PRINTER specifies 'DEV' as a COMENT, then the complete resource name is 'MODIFY.DEV'. Note that COMENT= on $SCANTABs which are not at the highest level of SCAN are ignored.

COMPMSG=

Specifies whether (YES) or not (NO) JES2 should display the $HASP894 DISPLAY COMPLETE after the $D command processing completes. A second parameter, which is optional, is used to specify the $BLDMSG id of a different message to be displayed when completed.

COMREJ=

Specifies under which circumstances commands should be rejected. The value allowed for this keyword is:

REMOTE: Rejects command if issued from a remote.

DELTEXT=

Specifies the text that JES2 appends to an element's display on a DISPLAY/DELETE request.

DEFAULT: Indicates that JES2 will append the default text, - ELEMENT DELETED on a DISPLAY/DELETE request.
NONE: Indicates that JES2 will not append any text on a DISPLAY/DELETE request.

DISPALL=

Specifies if this keyword is displayed on a display-all subscan request.

YES: Displays the keyword.
NO: Does not display the keyword.
LONGONLY: Displays the keyword only when you specify CONV=LONG on this macro call or LONG=YES on the $SCAN call.
NOTLONG: Displays the keyword only when the display-all is due to specifying CONV=LONG on this macro call or LONG=YES on the $SCAN call.

FILTER=

Specifies the type of filtering JES2 uses when processing this keyword.

(YES[ALWAYS,EQ,NEQ,GTLT,NODELIM,VORDER,NOVORDER,NOSET, NOGENERIC])

Specified as a filter like YES but with any of the following positionals:

ALWAYS: This keyword is always a filter when specified on a SET call. When ALWAYS is not specified on a SET call, you must precede it by a division slash (/) to be a filter.
EQ: A valid filter delimiter of equal (=).
NEQ: A valid filter delimiter of not equal (¬= or <>).
GTLT: Valid filter delimiters other than equal or not equal are allowed.
NODELIM: They keyword will be accepted as a filter when no filter delimiter is specified. This results in a match on a null VALUE= parameter.
VORDER: For CONV=VECTOR keywords, indicates that the vector elements must be in the same order as specified on the filter for a match to occur.
NOVORDER: For CONV=VECTOR keywords, indicates that the vector elements may occur in any order.
NOSET: Indicates that the filter is not allowed on a SCAN=SET call.
NOGENERIC: Generic characters * and ? are not to be treated as generics and must match exactly on character comparisons.

If EQ, NEQ, or GTLT is not specified, the default is as if all three were specified. If CONV=FLAG, the default is as if EQ and NEQ were specified.

NO

If you specify FILTER=YES on the $SCANTAB for a command, you can specify one or more selection criteria on the display command, and only when the parameter is equal to the value specified will the elements be displayed. If you specify FILTER=NO on the $SCANTAB for a command, then you can only specify one parameter on a display command. If you specify any other selection criteria, you will receive an error message.

SUBFLD=

Specifies where to find the search argument or field to match with the numeric subscript.

field: Identifies the field in each control block in the chain that will be compared to the numeric subscript, until a match is found.
dsect: Specifies the name of the DSECT for the control block.
length: Specifies the length of the field to be compared.

SUBSCRP=

Specifies an allowable subscript range for the input specifying this keyword. If SUBSCRP is specified, the allowable input forms for $SCAN are ‘keyword(subscript)’ and ‘keywordsubscript’. SUBSCRP is specified as a list of 2, 3 or 4 values, with the first being the lowest allowed subscript value and the second being the highest allowed value. The first and second operands must be numeric values with one exception; single character alphanumeric subscripts can be used, with ‘A’ corresponding to value X'C1', ‘4’ to value X'F4', and so on.

The optional third value specifies an index value optionally used during the search for the control block for this keyword. After (by default) or during the CBIND processing in that search, the subscript value is used to index into the current control block to find the correct sub-block for the keyword. The lowest subscript is assumed to correspond to the 0th sub-block and the length of each sub-block is defined by the third positional value of SUBSCRP.

The optional fourth value specifies that the “high” and “low” values are to be used as offset values into the HASP (HCT) or USER (UCT) control tables.

FIELD=

Specifies the name and length of the field associated with the keyword value in the specified control block. The field must be within the DSECT specified by DSECT=, or must be an absolute offset if DSECT=0 is specified. The length is defined by the second positional parameter, and defaults to the assembler-defined length of the field label. FIELD= is required unless CONV= is SUBSCAN, VECTOR or ALIAS.

DSECT=

Specifies the DSECT name required to resolve the field specified by FIELD= in the control block found by the $SCAN search. If FIELD= is specified as an absolute offset into the control block, DSECT should be specified as DSECT=0.

RANGE=

Specifies the allowed range for the input. For keywords for which CONV is NUM, HEX, or CHARN RANGE specifies a binary range. For keywords for which CONV is CHARxxxx, for CHARxxxx not equal to CHARN, RANGE specifies a length range. RANGE and VALUE are mutually exclusive.

RELATED=

Specifies a list of related $SCANTAB entries. You should use this parameter when you modify a $SCANTAB parameter that directly affects the value of another $SCANTAB call.

SSOPT=

Specifies whether (YES) or not (NO) a subscript specification is optional on all $SCAN call types.

For SCAN=DISPLAY calls, the subscript specification is always optional regardless of the value you specified here.

Attention: If you specify SSOPT=YES, JES2 assumes a subscript of (*) when a subscript is not specified.

VALUE=

Specifies the allowed specific values a keyword may have. VALUE is used to limit input to only certain values, instead of using RANGE to limit the input to a range of values. RANGE and VALUE are mutually exclusive.

For keywords for which CONV= is not specified as FLAG, this keyword is specified as a list of allowed values. Note that the input must match the VALUE= specification exactly. For example, if the value 000293 is specified as input, it is within the allowed range for RANGE=(66,400), that is between 66 and 400, but it does not match the VALUE=(36,2,99,293,4) specification, exactly.

For CONV=FLAG keywords, VALUE is specified as a list making up a set of triplets of input, that is VALUE=(a1,b1,c1,a2,b2,c2,...). For each set of three operands, as shown, the first (a) is the allowed value the keyword may have, the second (b) is a flag byte setting to ‘or’ on in the FIELD if the keyword is given this value, and the third (c) is a flag bytes setting to ‘and’ off in the FIELD. For example, to implement a keyword with values of YES or NO, which is represented by a single flag bit setting specify the following:

CONV=FLAG,VALUE=(YES,YESFLAG,FF,NO,0,FF - YESFLAG)

If the keyword have no input value, i.e., there is value in the keyword being specified alone, VALUE should consist of one triplet with the first operand null.

CALLERS=

Specifies one or more caller ids (in a parenthesized list) for which this scan table entry is to be used. If CALLERS is not specified, the table entry is used for any $SCAN caller. This operand is useful, for example, when a scan table is to be used for multiple parameter statement purposes and not all keywords are valid in every case. Note that $SCAN supports multiple entries specified in a scan table for the same NAME= keyword with different CALLERS= specifications. Valid callers are:

Valid Callers: Identifies the:
$SCOPTS: JES2 initialization options (for example, COLD, WARM, REQ, NOREQ)
$SCIRPL: JES2 initialization statements
$SCIRPLC: console-issued commands during JES2 initialization
$SCDCMDS: display commands in HASPCOMM
$SCSCMDS: set commands in HASPCOMM
$SCDOCMD: short forms of the display commands
$SCSTCMD: start commands
$SCPCMDS: stop commands
$SCDDIAL: dialog display form
$SCSDIAL: dialog set form
$SCECMDS: reset commands
$SCACMDS: add commands in HASPCOMM
$SCRCMDS: delete commands in HASPCOMM
$SCLTCMD: Output long display
$SCECMDA: RESET COMMANDS (single)
$SCZCMDS: HALT commands
$SCHCMDS: HOLD commands
$SCRLCMD: RELEASE commands
$SCCCMDS: CANCEL commands
$SCTOCMD: $TO commands
$SCCOCMD: $CO commands
$SCPOCMD: $PO commands
$SCOCMDS: $O command
$SCLOCMD: Output short display
$SCLCMDS: $L command

PRESCAN=

Specifies the name of one or more routines to be entered just after determining the parameter input contains this keyword and before scanning the input any further. The routine does not have to be in the same CSECT as the table. Register 1 points to the scan work area (SCWA) on entry to the routine and the routine can change the SCWA fields and use return codes to direct the actions of $SCAN. An optional second positional parameter of SET, DISPLAY, FILTER, or DELETE on PRESCAN after each PRESCAN routine name indicates that the PRESCAN routine should be called only for the specified $SCAN calls. You can specify more than one of these parameters for each routine name.

Values of HCT, HCCT, or CR11 can also be specified as positionals after the routine name to influence the contents of R11 on entry to the routine; these might be required in some multi-environment cases. If not specified, the value of R11 will be set as follows:

HCT, if the routine address is in the PADDR, UPADDR, SXADDR, or USXADDR;
HCCT, if the routine address is in the CADDR or UCADDR, or if the $SCANTAB is assembled in the USER assembly environment;
CR11, if none of the above apply.

Specify CR11 if the value of register 11 at the time of the $SCAN call is to be used. If none of HCT, HCCT, or CR11 is specified, then a default is used.

PSTSCAN=

Specifies the name of one or more routines to be entered after all scanning (including possible subscanning) is done for this keyword. PSTSCAN= and the routine interface are the same as those for PRESCAN=.

SCANTAB=

Specifies another one or more scan tables or table entry required when scanning this keyword. For CONV=ALIAS, it specifies the address of another scan table entry defining the keyword of which this keyword is an alias. For CONV=VECTOR, it specifies the address of another complete scan table defining the values allowed for each element of the vector. For CON=SUBSCAN, it specifies the address of a doubleword containing the addresses of two complete scan tables, for example, one user scan table and one JES2 scan table, to be used in the recursive $SCAN call that performs the subscanning required.

If CONV=VECTOR or CONV=SUBSCAN is specified, the pointer to the next set of scan tables is calculated as an offset into either the MCT or UCT. This is specified by the second positional operand on this keyword. For example:

$SCANTAB SCANTAB=(MCTPRTU,MCT)...

generates (MCTPRTU – MCT) for the offset into the $MCT of the scan table pair.

$SCANTAB SCANTAB=(UCTPRTU,UCT)...

generates (UCTPRTU – UCT) for the offset into the $MCT of the scan table pair.

$SCANTAB SCANTAB=(OWNPAIR,ADDR)...

generates (OWNPAIR – ADDR) as the address of the table pair.

$SCANTAB SCANTAB=(OWNPAIR,VCON)...

generates (OWNPAIR – VCON) as the VCON of the table pair.

VCOUNT=

Specifies the number (1-255) of vector elements this scan table entry defines. VCOUNT is ignored if it is specified for an entry in a scan table that is specified to SCANTAB= for a CONV=VECTOR keyword. It allows a single scan entry to define multiple elements of a vector, with the associated fields for the elements being FIELD, FIELD plus the field length, FIELD plus twice the field length, and so on. The default is a value of 1.

An second positional parameter of IGNORE in VCOUNT, which is optional, indicates that null input for vector elements is allowed and the associated fields should not be changed in any way.

An third positional parameter, which is optional, specifies the size of a vector element. This is the number of bytes that must be added to the current vector element to locate the next element. The default is the size of the field. A value of 0 indicates to use the same field for all elements, for example, a postscan exit is processing the elements.

OBS=

Specifies whether the keyword specified for NAME= is to be considered obsolete (the default is OBS=NO). If OBS is specified as YES, $SCAN should consider it to be an error if this keyword is found during a scan, but return a less severe return code and message to the caller.

MINLEN=

Specifies the minimum character length of the keyword defined by this $SCANTAB entry that may be used to reference the keyword in parameter input. For example, if NAME=FORMS is specified, and MINLEN=2, then: FO, FOR, FORM, and FORMS are valid keyword references; F, FOX, and FORMSX are invalid. If MINLEN= is not specified, the valid keyword specification is the entire keyword; no abbreviated forms are allowed.

MSGID=

Specifies the 3 or 4-digit message ID for the $HASPnnn message identifier that is used when a SCAN=DISPLAY includes a display line in a $SCAN call. This message ID is ignored by $SCAN except at the highest level of scanning. For example, it is used for the PRINTERnn statement, but it is ignored for the FORMS= keyword on the PRINTERnn statement.

DISPKEY=

Specifies whether (YES) or not (NO) the keyword name is displayed as part of the $SCANTAB output. If YES is specified, the keyword specified by NAME= on this macro is displayed with its value. If NO is specified, only the value assigned to the keyword is displayed.

TEXT=

Specifies the text string produced by this $SCANTAB call if SCAN=(DISPLAY,ALL) is specified on the $SCAN macro instruction. You can specify a character string up to 255 characters; enclose the string in single quotation marks.

Note: If TEXT= is specified, do not also specify NAME= or TABLE=.

TOKEN=

Specifies the address of a control block that is passed to the $SCAN routines, PRESCAN, POSTSCAN, and DISPLAY.

DISPLAY=

Specifies whether (YES) or not (NO) the value assigned to a keyword is displayed as part of the $SCANTAB output. If YES is specified, the value associated with the keyword specified by NAME= on this macro is displayed. If NO is specified, the value associated with the keyword specified by NAME= on this macro is not displayed.

CRLF=

Specifies whether (YES) or not (NO) the line of message text added by this SCANTAB call is displayed following a carriage return and line feed (that is, displayed on a new line) during display processing. The default, NO, specifies the additional text is appended immediately after the existing message text. A second optional value is the line type for multi-line WTOs. Valid values are C, L, D, DE, and E. These are only valid if CRLF=YES. See the WTO macro for complete descriptions.

ROUT=

Specifies the route codes to which this message is to be routed. These values are passed to the display routine for processing. This route code is ignored by $SCAN except at the highest level of scanning. If you provide more than one code, separate each by a comma and enclose the list in parentheses.

DESC=

Specifies the descriptor codes for this message that are passed to the display routine for processing. This descriptor code is ignored by $SCAN except at the highest level of scanning. If you provide more than one code, separate each by a comma and enclose the list in parentheses.

JESROUT

Specifies whether (YES) or not (NO) the JES specific route code of 42 is to be used. The default is NO. It is only used by $BLDMSG and ignored by $SCAN.

DISPERS=

Specifies a list of flag bits that must be set on in the flag byte specified on the DISPER= keyword for the call to the SCAN macro if this SCANTAB is to be used. If the required bits are not set on, this SCANTAB will not be used.

ACTDISP=

Specifies the activity condition required for display of this keyword. ACTIVE indicates display only in the case of activity; INACTIVE indicates display in case of inactivity; and BOTH indicates display regardless of activity. the ACTFLAG bit is used to determine whether or not there is activity. ACTDISP=BOTH is the default.

ACTFLAG=

Defines a field in the control block pointed to by CB, CBIND, and SUBSCRP= that is used to determine if there is any activity on the logical (for example, node) or physical (for example, printer) device. If any bits are on (set to 1), activity is assumed and the ACTSET= keyword determines if a set-type $SCAN is permitted.

If CB=PRESCAN or CB=TEMP is specified, $SCAN ignores the ACTFLAG parameter.

ACTSET=

Specifies the activity condition required for a set-type $SCAN call. ACTIVE indicates activity is required; INACTIVE indicates that inactivity is required; and BOTH indicates a set-type $SCAN call is allowed regardless of activity. The ACTFLAG bit is used to determine whether or not there is activity. ACTSET=BOTH is the default.

GENSET=

Specifies whether (YES) or not (NO) a set-type $SCAN call is permitted for generic requests. A generic request is one that includes an asterisk (*) within the symbolic subscript, for example, PRT(99-*). GENSET= does not affect the processing of range requests, for example, PRT(99-999). GENSET=YES is the default.

LKUPFLD=

Specifies an argument used to locate a control block. As part of a CB= or CBIND= search, the LKUPFLD= specification is used to match the specified symbolic subscript. If CB= and CBIND= are not used, LKUPFLD= is used as the search argument for the control blocks defined by SUBSCRP=.

SCAN=

Specifies the call types that can be used by $SCAN to call $SCANTAB. The list of valid calls is all the scan call work area (SCWA) equates from the SCWATYPE field, for example SCAN=SCWASET+SCWADISP+SCWACR allows set-, display-, and create-type $SCAN calls. If SCAN=SCWASET+SCWACR is specified, display-type calls are invalid. If SCAN= is not specified, all call types are allowed.

WARNING=

A one-byte warning mask that indicates when this scan table entry should be halted and a warning-level diagnostic message sent to the caller. This warning mask will be compared with the mask specified by WARNMSK= on the $SCAN macro call. If any bits match, the SCAN process will be halted.

JOB=YES | NO

Specifies whether a display of this table entry by a subsequent $SCAN macro is to include a job identifier. Code this parameter only on high-level $SCANTAB entries.

YES: Include the job identifier in the display.
Code YES only if you are defining a table entry that modifies an IBM-defined command. For a list of the IBM-defined commands that you can modify through the $SCANTAB macro, see Table 1. If you code YES, you must have previously set PCE field PCEJQE to point to the JQE that corresponds to the JOE to be displayed.
NO: Do not include the job identifier in the display. This is the default.

FILTER_XCLUDE=

Specifies a list of $SCANTABs that represent filters. The filters are mutually exclusive with this filter keyword.

WIDTH=nnn

Indicates the number of places in the output area (from 1 to 32) to be used to display the results. This is only valid with CONV=NUM (right justified), CONV=HEX (left justified), or CONV=CHAR (right or left justified). This parameter is optional.

COMPCE

Specifies the identifier (sequence number) of the command processor (PCE) that will process the command defined by this table. The default value is $CMDNORM (0).

Note: COMPCE= on $SCANTABs that are not at the highest level of scan will be ignored.

Format description

Boundary form

Entry form

Environment