SCAN

Read syntax diagramSkip visual syntax diagram label SCAN TEXT = '  text ' (  addr ,  length , (  reg ) ) ( (  reg ) ,  length , (  reg ) ) 1, BUFFER = (  addr ,  length , (  reg ) ) ( (  reg ) ,  length , (  reg ) ) , TRANS = NO , TRANS = YES (  reg ) (  addr ,  mask ) , ERROR = * , ERROR = addr (  reg ) 2, MF = L ( L ,  addr ,  mf_label ) ( E ,  addr )
Notes:
  • 1 Keyword parameters can be entered in any order.
  • 2 Default is the standard macro format.

Purpose

Use the SCAN macro to build tokenized and extended parameter lists and optionally translate an input line.

Parameters

Required Parameters:
TEXT=
is the input data to be scanned. Acceptable values are:
'text'
scans the data enclosed in the quotation marks.
(addr,length)
specifies the address of the data as an assembler expression and, optionally, specifies the length as an absolute expression.
(addr,(reg))
specifies the address of the data as an assembler expression and, optionally, specifies the length of the data as a value contained in a register. Valid registers are 2-12 enclosed in parentheses.
((reg),length)
specifies a register that contains the address of the data and specifies the length of the data as an absolute expression. If you use a register to specify the address, you must specify a length.
((reg),(reg))
specifies a register that contains the address of the data and a register that contains the length of the data. If you use a register to specify the address, you must specify a length. Valid registers are 2-12 enclosed in parentheses.
BUFFER=
is a user-provided buffer to contain the extended and tokenized parameter lists. You must specify a buffer large enough to contain the extended parameter list, all of the tokenized arguments, and an 8-byte fence delimiting the end of the tokenized parameter list—a minimum of 48 bytes. Acceptable values are:
(addr,length)
specifies the buffer address as an assembler expression and, optionally, specifies the buffer length as an absolute expression.
(addr,(reg))
specifies the buffer address as an assembler expression and, optionally, the buffer length as a value contained in a register. Valid registers are 2-12 enclosed in parentheses.
((reg),length)
specifies a register that contains the buffer address and specifies the buffer length as an absolute expression. If you use a register to specify the address, you must specify a length.
((reg),(reg))
specifies a register that contains the buffer address and a register that contains the buffer length. If you use a register to specify the address, you must specify a length. Valid registers are 2-12 enclosed in parentheses.
Optional Parameters:
label
is an optional assembler label for the statement.
TRANS=
indicates whether CMS translates the input. Acceptable values are:
NO
indicates that CMS will not translate the input. No translation, including uppercase translation, is done to the input when building both the tokenized and extended parameter list. This is the default value.
YES
specifies that CMS use the user translate table (created with the CMS SET INPUT command) to translate the input data. If you have not created a user translate table, CMS uses the system uppercase translate table. If you have created a user translate table, CMS uses the system uppercase translate table with the changes specified by the SET INPUT command applied when building both the tokenized and extended parameter lists.
(reg)
specifies the register to be checked by the macro. If the value is 0, the macro sets TRANS to NO. If the register contains a nonzero value, the macro sets TRANS to YES.
(addr,mask)
defines a single bit in storage that sets the value of the TRANS parameter. The addr is the address of a byte in storage and the mask determines which bit within the byte the macro tests. You can specify addr and mask in any form allowed on a TM assembler instruction. If the specified bit is 0, then TRANS is set to NO. If the bit is 1, then TRANS is set to YES. For example, to test the first bit in the single byte of storage at location APPFLAG, specify the TRANS parameter as 
TRANS=(APPFLAG,X'80')

To set the value of the TRANS parameter at assembly time, specify TRANS=YES or TRANS=NO. The default value is TRANS=NO. To set the value at execution time, specify TRANS=(reg) or TRANS=(addr,mask).

ERROR=
specifies an action to be taken if an error occurs. If you do not specify the ERROR= parameter, control passes to the next sequential instruction. Acceptable values are:
*
passes control to the next sequential instruction. This is the default value.
addr
passes control to the specified address.
(reg)
passes control to the address in the specified register.
Note: Do not specify the ERROR= parameter with the list (MF=L) or complex list (MF=(L,addr,mf_label)) macro forms.
MF=
specifies the macro form. Omitting the MF parameter specifies the standard format. For more information about the MF parameter, see CMS Macro Formats. Acceptable values are:
L
specifies the list format.
(L,addr,mf_label)
specifies the complex list format. Specify addr as an assembler expression or as a register enclosed in parentheses. The mf_label parameter is optional.
(E,addr)
specifies the execute format. Specify addr as an assembler expression or as a register enclosed in parentheses.

Usage Notes

  1. When the SCAN macro completes successfully, it stores the address of the tokenized parameter list in register 1 and the address of the extended parameter list in register 0.
  2. The SCAN macro creates a tokenized parameter list and an extended form parameter list in the following format: 
       DC A(CMNDNAME)          Command name
   DC A(BEGARG)            Beginning of argument list
   DC A(ENDARG)            End of argument list
   DC F'0'                 User word
   DC A(0)                 Address of function argument list
   DC A(0)                 Address for return of function data
   DC 2F'0'                Padding
   DC CL8'        '        Tokens (as required)
   DC CL8'        '        Tokens (as required)
   DC X'FFFFFFFFFFFFFFFF'  Fence
    The SCAN macro uses EPLIST to map the extended parameter list.

Return Codes

If an error occurs, register 15 contains one of the following return codes:
Code
Meaning
4
The user-supplied buffer area is too short to contain all of the tokens in the tokenized parameter list. The list is truncated.
8
The user-supplied buffer area is less than 48-bytes.
104
CMS is unable to obtain enough storage to do the translation.