INTRPRET—Interpret an input sequence

Purpose

For each device-type logical unit, INTRPRET allows an application program to use interpret tables to convert an input character sequence into an output character sequence.

Usage

This function uses interpret tables that are specified by the user and maintained by VTAM®, rather than tables that are created and maintained by each application program.

During VTAM definition, the user identifies each device-type logical unit in the domain and optionally associates an interpret table with each one. The interpret table contains one or more variable-length sequences that the device-type logical unit is capable of sending—such as graphic characters, tab characters, or program function key characters. With each of these sequences, the user specifies a corresponding 8-byte sequence (or the address of a user-written routine that generates an 8-byte sequence). An application program issuing INTRPRET identifies the device-type logical unit and provides a particular sequence received from the logical unit; VTAM, if it finds that sequence in the interpret table for that logical unit, returns the corresponding sequence to the application program.

Note: Do not define an interpret table for other application programs, or use it to interpret data from a logical unit in another domain. Refer to the z/OS Communications Server: SNA Resource Definition Reference for details on interpret tables.

As an example, assume that the user defines the following interpret table for logical unit T3270:

Symbol	T3270 interpret table
LGN	LOGON
#	REPEATLT
@	LIST

If the application program specifies T3270 and provides any sequence beginning with # to INTRPRET, INTRPRET would return the corresponding sequence—in this case, REPEATLT—to the application program.

Before issuing the INTRPRET macroinstruction, the application program must set register 13 to the address of an 18-word save area. Refer to Summary of register usage, for information pertaining to the register contents upon return of control.

VTAM receives control from the INTRPRET macroinstruction in the addressing mode of the application program that issued the macroinstruction and returns control to the application program in that same mode.

For output, the name placed in the AAREA field depends on whether PARMS=(NQNAMES=YES) or PARMS=(NQNAMES=NO) on the ACB macroinstruction:

If PARMS=(NQNAMES=NO) on the ACB macroinstruction, the 8-byte name is returned.
If PARMS=(NQNAMES=YES) on the ACB macroinstruction, the 16-byte network-qualified name is returned. The format of the returned data is the 8-byte network identifier (padded with blanks if necessary) followed by the 8-byte resource name (padded with blanks if necessary).

Syntax


>>-+------+--INTRPRET--RPL--=--rpl_address---------------------->
   '-name-'                                  

>--+----------------------------------------------+------------->
   |                                          (1) |   
   '-,--AAREA--=--alternate_data_area_address-----'   

>--+-----------------------------------------------+------------>
   |                                           (1) |   
   '-,--AAREALN--=--alternate_data_area_length-----'   

>--+----------------------------+------------------------------->
   |                        (1) |   
   '-,--ACB--=--acb_address-----'   

>--+-----------------------------------+------------------------>
   |                               (1) |   
   '-,--AREA--=--user_data_address-----'   

>--+-------------------------------+---------------------------->
   |                           (1) |   
   +-,--ARG--=--(--register--)-----+   
   |                        (1)    |   
   '-,--NIB--=--nib_address--------'   

>--+---------------------------+-------------------------------->
   |                       (1) |   
   '-,--BRANCH--=--+-NO--+-----'   
                   '-YES-'         

>--+--------------------------------------+--------------------->
   |                     (1)              |   
   +-,--ECB--=--INTERNAL------------------+   
   +-,--ECB--=--ecb_address---------------+   
   |                                  (1) |   
   '-,--EXIT--=--exit_routine_address-----'   

>--+--------------------------+--------------------------------->
   |                      (1) |   
   '-,--OPTCD--=--+-ASY-+-----'   
                  '-SYN-'         

>--+------------------------------------+----------------------><
   |                                (1) |   
   '-,--RECLEN--=--user_data_length-----'

Notes:

Operand value can be placed in its RPL field either by specification on an RPL macroinstruction operand or by explicitly setting the field using the IFGRPL DSECT.

Input parameters

RPL=rpl_address: Indicates the RPL that specifies which kind of processing INTRPRET is to perform.

The following RPL operands apply to the INTRPRET macroinstruction:

AAREA=alternate_data_area_address

Indicates the data area where VTAM is to place the interpreted sequence.

AAREALN=alternate_data_area_length

Indicates the length of the data area where VTAM is to place the interpreted sequence. If NQNAMES=NO, this value should be at least 8. If NQNAMES=YES, this value should be at least 16.

ACB=acb_address

Indicates the ACB that identifies the application program issuing INTRPRET.

AREA=user_data_address

Indicates the data area containing the sequence being submitted to VTAM for interpretation.

ARG=(register)

Indicates the register containing the CID of the session with the device-type logical unit. VTAM searches for an interpret table for the associated device-type logical unit. If the ARG operand is not specified, the RPLARG field must contain an NIB address.

BRANCH

For application programs running in supervisor state under a TCB, BRANCH indicates whether authorized path processing is to be used. See Authorized path.

BRANCH=YES: When the macroinstruction is issued, VTAM processes the macroinstruction using authorized path. For programs running under an SRB rather than under a TCB, the macroinstruction is processed in this manner automatically, regardless of the actual setting of the BRANCH field.
BRANCH=NO: When the macroinstruction is issued, VTAM does not process the macroinstruction using authorized path.

ECB

Indicates that an ECB is posted when an asynchronous (OPTCD=ASY) INTRPRET operation is posted as being complete. You cannot specify both ECB and EXIT on a single macroinstruction.

ECB=event_control_block_address: Specifies that VTAM is to post an event control block (ECB). Event_control_block_address is the location of the ECB to be posted. The ECB can be any fullword of storage aligned on a fullword boundary.
ECB=INTERNAL: Specifies that VTAM is to post an internal ECB.

EXIT=exit_routine_address

Indicates the address of an RPL exit routine that is scheduled when an asynchronous (OPTCD=ASY) INTRPRET operation is posted as being complete. You cannot specify both ECB and EXIT on a single macroinstruction. For details about the EXIT operand, refer to the RPL macroinstruction description in this chapter.

NIB=nib_address

Indicates the NIB whose NAME field identifies the device-type logical unit and if using NQNAMES, indicates the NIB whose NIBNET field contains the network identifier of the logical unit. VTAM searches for an interpret table for this device-type logical unit. If the NIB operand is not specified, the RPLARG field must contain a CID.

Note: If your application uses the RPL DSECT, IFGRPL, you must set the RPLNIB bit if an NIB address is being inserted into the RPLARG field.

OPTCD=SYN

OPTCD=ASY

If the SYN option code is set, control is returned to the application program when the INTRPRET operation has been completed. If the ASY option code is set, control is returned as soon as VTAM has accepted the request. After the INTRPRET operation has been completed, the ECB is posted or the RPL exit routine is scheduled, depending on the setting of the ECB-EXIT field. Refer to the RPL macroinstruction description in this chapter for details about OPTCD=SYN or OPTCD=ASY.

Because it might take VTAM a relatively long time to complete the INTRPRET operation, you should not use the SYN option if suspending the INTRPRET-issuing task or SRB for this time is undesirable. Use the ASY option code, instead.

RECLEN=user_data_length

Indicates how many bytes are being submitted to VTAM for interpretation. If a sequence in the interpret table is shorter than the value in RECLEN, and yet is identical to the corresponding initial part of the data pointed to by AREA, the sequences are considered matched. Refer to the z/OS Communications Server: SNA Resource Definition Reference for coding information on the logon-interpret routine. RECLEN must be set to 255 (decimal) or less.

Examples

INT1     INTRPRET RPL=RPL1,                                            C
               NIB=NIB6,AREA=INSEQ,RECLEN=(3),                         C
               AAREA=OUTSEQ,AAREALN=8
         .
         .
         .
RPL1     RPL
INSEQ    DS    CL180
NIB6     NIB   NAME=LU1
OUTSEQ   DS    CL8

An application program has read a block of data from LU1 and issues INT1 to interpret that data. NIB6 identifies the LU (and therefore, the interpret table to be used), AREA indicates the data area containing the data to be interpreted (INSEQ), and RECLEN indicates that the amount of data to be interpreted is in register 3. If INTRPRET uses the same RPL that was used to read the data, the NIB-ARG field, the AREA field, and the RECLEN field are already correctly set.

Upon completion of INT1, the corresponding sequence is placed in the data area identified by the AAREA field (OUTSEQ). Although two separate data areas have been provided in this example for the “input” data (INSEQ) and the “output” data (OUTSEQ), there is no reason why the same data area could not be used.

Completion information

The INTRPRET operation is successfully completed as soon as the output character sequence has been placed in the application program's storage area.

When the INTRPRET operation is completed, these RPL fields are set:

The value 27 (decimal) is set in the REQ field, indicating an INTRPRET request.
If the FDB2 field indicates that INTRPRET failed because the data to be placed in the AAREA work area, (RTNCD,FDB2)=(X'00',X'05'), does not fit, the ARECLEN field contains the number of bytes required to hold the data. If INTRPRET is completed successfully, the ARECLEN field indicates how many bytes of data have actually been placed in the AAREA work area.
The RTNCD and FDB2 fields are set as indicated in Return codes and sense fields for RPL-based macroinstructions.
If the macroinstruction returns an error code, the SSENSEI, SSENSMI, and USENSEI fields can be set indicating system-sense information, system-sense modifier, and user-sense information. See Return codes and sense fields for RPL-based macroinstructions for more information about these fields.

Registers 0 and 15 are also set as indicated in Handling errors and special conditions.