gtps2m1c | ACF/SNA Data Communications Reference |
The side information table offline program (CHQI) runs under MVS or CMS to generate either a tape or a general data set that can be loaded to a TPF system. The generated data set contains commands and data for modifying the side information table. Data from the side information table is retrieved whenever an application transaction program issues the mapped conversation initialize conversation (cminit) function.
Figure 53 shows the process for generating a side information table.
Figure 53. Generating the Side Information Table
The steps required for generating a side information table are as follows:
The input to CHQI is an EBCDIC file of fixed-length 80-byte records, consisting of statements that specify the function to be performed. You can also include comments and blank lines to improve readability. See Creating the Input File for details.
CHQI creates 2 output files:
See Running CHQI and Side Information Table Offline Program Output for details.
Steps 5, 6, and 7 are described in more detail in Loading the Side Information Data Set to TPF.
In the following discussion, the phrase side information table refers to the online side information table residing on TPF. The phrase side information data set refers to the data set that is generated offline by CHQI and contains the entries for the online side information table.
The following describes the basic steps for creating the input file for CHQI. Additional details on the syntax requirements for the statements are described in the following section, Statement Syntax.
where subsystem is the 1- to 4-character name of the subsystem on which the data is to be loaded. If you specify a subsystem, the side information data set must be loaded to that subsystem. If you do not code a LOAD statement, the side information data set can be loaded to any subsystem. After the side information data set is loaded, the symbolic destination names defined by that data set are available to transaction programs running in the specified subsystem. You can specify only 1 subsystem for a side information data set; that is, only 1 LOAD statement can be included in the input file. This statement, if included, must precede all other statements.
where text is the line of text to be displayed. The text is displayed as a response to the ZNSID LOAD command.
where sdn is the symbolic destination name of the new entry, tpn is the corresponding remote transaction program name, lun is the corresponding partner LU name, and mode is the corresponding mode. If an entry with the identical symbolic destination name already exists in the side information table, it is changed by the entry in the side information data set. If 2 or more entries with the same symbolic destination name are included in the same side information data set, the entries are loaded in the order that they are specified in the input file. After the load is complete, the side information table entry for the duplicated symbolic destination name contains the data specified for the last entry loaded.
where sdn is the symbolic destination name of the entry to be removed. If no entry with the specified symbolic destination name exists in the table, the entry in the side information data set is ignored.
The CHQI input syntax consists of the following elements:
The input file is free format in that you do not have to code verbs and parameters on a particular line or in a particular column. Blank lines can be inserted at any point to improve readability. Exceptions to this free format include the following:
CHQI's parser scans the input file, strips out comments, and parses the remaining text into tokens. A token is any string of characters that is delimited by a space, null character, comma3, dash, equal sign, or logical end of record and that does not contain a space, null character, dash, equal sign or logical end of record4.
Tokens are classified as verbs, parameter keywords, and parameter values. Each verb begins a new statement, and each statement consists of the verb that initiates it and any following parameters up to the next verb or the end of file. The statements are checked for errors. Any statement containing no error messages or only attention messages is written to the side information data set in the proper format to be read by the TPF side information data loader. Statements containing 1 or more errors are not written to the side information data set.
The following shows the format of the statements and describes the verbs and parameters.
LOAD SS-subsystem
The SS parameter value is any string from 1 to 4 characters long. The subsystem name is copied to the header of the first record in the side information data set.
DESCR text
ADD NAME-sdn TP-tpn LU-lun MODE-mode
If any of these parameters is repeated in a single ADD statement, it is flagged as an error. (Successive TP parameters, which are concatenated, are treated as a single instance of the TP parameter.)
The NAME parameter value is any string from 1- to 8-characters long, consisting of any characters except token delimiters (dash, equal sign, comma, or blank) and lowercase letters. The symbolic name written to the side information data set is an 8-byte field consisting of the NAME parameter value padded to the right with space characters.
SNA allows transaction program names to include unprintable characters. To allow entry of such names, the TP parameter value can include substrings that are translated to unprintable characters in the output side information entry. The generated transaction program name is a variable-length field from 1 to 64 bytes long with no padding.
The dollar sign ($, X'5B') is used to delimit substrings of TP parameter values that are to be interpreted as hexadecimal values, according to the following rules:
To accommodate the possibility of a TP parameter value being too long to fit into 1 80-byte record, the values of adjacent TP parameters are concatenated. Each of the parameter values must conform to the rules stated previously, and the total length of all the concatenated converted strings must be less than or equal to 64. No other parameters can be coded between 2 concatenated TP parameters.
The following example shows adjacent TP parameters that are concatenated to produce 1 transaction program name value for the generated entry:
************************************************** * ADD STATEMENT WITH CONCATENATED TP PARAMETERS. * * THE GENERATED TRANSACTION PROGRAM NAME IS: * * HEX : C2C5C7C9 D5010203 5BC5D5C4 * * EBCDIC : B E G I N . . . $ E N D * ************************************************** ADD N-CONCAT T-BEGIN T-$010203$ T-$$ T-END ...
The LU parameter value is a string from 1 to 17 characters long, consisting of an LU name and an optional network ID. If the network ID is included, it must precede the LU name and be separated from it with a period. If you only include the LU name, a period is not required.5 Both the network ID and the LU name must be from 1 to 8 characters long, must contain only capital letters (A-Z) and numeric digits (0-9), and must begin with a capital letter. Any LU parameter that does not satisfy these requirements is flagged as an error. The following are examples of valid LU parameter values:
NETID.LUNAME LUNMONLY N112358D.L1234567 N.L LU62MAPD
The partner LU name field written to the side information data set is a variable-length field from 1 to 17 bytes long. The LU parameter value is copied to it without conversion or padding.
The MODE parameter value is a string from 1 to 8 characters long. It must contain only capital letters (A-Z) and numeric digits (0-9), and must begin with a capital letter. Any MODE parameter value that does not satisfy these requirements is flagged as an error. The mode field written to the side information data set is a variable-length field from 1 to 8 bytes long. The MODE parameter value is copied to it without conversion or padding.
REMOVE NAME-sdn
Figure 54 shows an example of a CHQI input file.
Figure 54. Example of an Input File for CHQI
******************************************************************************** * THIS CHQI INPUT FILE GENERATES A TPF-LOADABLE SIDE INFORMATION DATA SET THAT * * REMOVES SOME OBSOLETE SIDE INFORMATION TABLE ENTRIES AND ADDS SOME NEW 1S. * ******************************************************************************** LOAD S-BSS ******************************************************************************** * IF CODED, THE LOAD STATEMENT MUST BE THE FIRST STATEMENT IN THE INPUT FILE. * * COMMENTS AND BLANK LINES CAN PRECEDE THE LOAD STATEMENT. * ******************************************************************************** DESCR ============================================== DESCR = REVISIONS TO SIDE INFORMATION TABLE = DESCR = CREATED 01/30/91 = DESCR ============================================== ********************************************************** * THE FOLLOWING ENTRIES ARE OBSOLETE AND WILL BE REMOVED * ********************************************************** REMOVE N-OBSDEST1 REMOVE N-OBSDEST2 REMOVE N-OBSDEST3 DESCR ============================================== DESCR = OBSOLETE ENTRIES HAVE BEEN DELETED = DESCR ============================================== ******************************************* * THE FOLLOWING NEW ENTRIES WILL BE ADDED * ******************************************* ADD N-NEWDEST1 T-TPNAME1 L-SNANET.LU62MAP1 M-MODE1 ADD N-NEWDEST2 T-TPNAME2 L-SNANET.LU62MAP2 M-MODE2 ADD N-NEWDEST3 T-TPNAME3 L-SNANET.LU62MAP3 M-MODE3 DESCR ============================================== DESCR = NEW ENTRIES HAVE BEEN ADDED = DESCR ============================================== |
Figure 55 shows how the TPF operator console looks after loading the side information data set generated from Figure 54.
Figure 55. TPF Console Display. This shows the result of loading the side information data set generated using the input in Figure 54.
+--------------------------------------------------------------------------------+ |NSID0017I 01:23:45 USER TEXT FROM SIDE INFORMATION GDS | |============================================== | |= REVISIONS TO SIDE INFORMATION TABLE = | |= CREATED 01/30/91 = | |============================================== | |--- END OF DESCRIPTION --- | | | |NSID0017I 01:23:45 USER TEXT FROM SIDE INFORMATION GDS | |============================================== | |= OBSOLETE ENTRIES HAVE BEEN DELETED = | |============================================== | |--- END OF DESCRIPTION --- | | | |NSID0017I 01:23:46 USER TEXT FROM SIDE INFORMATION GDS | |============================================== | |= NEW ENTRIES HAVE BEEN ADDED = | |============================================== | |--- END OF DESCRIPTION --- | | | |NSID0005I 01.23.46 NEW SIDE INFORMATION TABLE ENTRIES LOADED | |ENTRIES PROCESSED - 6 | |ENTRIES ADDED - 3 | |ENTRIES CHANGED - 0 | |ENTRIES REMOVED - 3 | |ERRORS DURING LOAD - 0 | | | +--------------------------------------------------------------------------------+
The syntax of the CHQI input file is similar to the syntax of the ZNSID command. The main differences between CHQI input statements and ZNSID commands are as follows:
If the NAME parameter of a ZNSID ADD command matches the symbolic destination name of an entry in the side information table, the command is rejected. If the NAME parameter of a CHQI ADD statement matches the symbolic destination name of an entry already in the side information table when the side information data set is loaded, the entry loaded from the side information data set replaces the online entry.
Consider, for example, there is an entry in the table for a symbolic
destination name of SYMDEST0. An input file contains the
statement:
ADD N-SYMDEST0 M-MODE0
(the LU and TP parameters are not specified). When the input file is processed, attention messages are generated stating that the LU and TP parameters are missing. After the resulting data set is loaded to TPF, the entry for SYMDEST0 contains the value for MODE which was specified by the input file; the values for LU and TP remain as they were before the new data was loaded.
CHQI consists of a single CSECT that can be assembled, link-edited, and run under either MVS or CMS. There are no runtime parameters for CHQI, but you must define the following 3 data sets:
The side information data set is described further in Side Information Data Set.
The contents of the output listing is described in CHQI Output Listing.
The following is a list of the possible return codes from CHQI.
The following is a sample of the JCL to create a tape under MVS:
//* Your JOB card here //************************** //* Execute CHQI * //************************** //CHQIRUN EXEC PGM=CHQI41 //STEPLIB DD DSN=TPF.BASE.RLSE.LK,DISP=SHR //SYSUDUMP DD SYSOUT=* //CHQIIN DD DSN=TPF.BASE.SIDINPUT(NEWSID),DISP=SHR //CHQILIST DD SYSOUT=* //SIDOUT DD UNIT=(TAPE,,DEFER),DISP=(NEW,KEEP),LABEL=(,SL), // DSN=SIDTAPE,VOL=SER=xxxxx /*
The following is a sample of the commands to create a tape under CMS:
FILEDEF CHQIIN DISK SIDTAPE INPUT A FILEDEF CHQILIST DISK SID LISTING A FILEDEF SIDOUT TAP SL CHQI
As stated earlier, CHQI generates 2 output files: a side information data set that can be loaded online by TPF and an output listing describing the results of the conversion of the input file to the side information data set.
A side information data set consists of entries containing data to be added to or removed from the side information table, or descriptive text to be displayed during the load. The entries are grouped into TPF 4K (4095-byte) records.
Each record consists of an 80-byte header and forty 100-byte entries. The byte following the last entry is used as an end-of-data indicator. The 14 remaining bytes at the end of the record are not used and are set to binary zeros. The data format in the record header and the entries is defined by the ISIDE data macro.
The CHQI output listing is a file of fixed-length 95-byte records. The first byte of each record is an ANSI printer control character. The listing echoes the input file with each line numbered and with attention or error messages interspersed among the input lines. The last page of the listing is a summary of the number of entries written to the side information data set and a summary of error and attention messages.
All attention and error messages begin with the prefix CHQI and are fully described in Messages (System Error and Offline) and Messages (Online).
The last page of the listing is a short summary of the processing that took place. There are 3 sections to the summary.
The first section describes the entries that were written to the side information data set. It includes a message telling which subsystem the data must be loaded to, or that the data can be loaded to any subsystem, the number of ADD entries generated, the number of REMOVE entries generated, and the number of lines of descriptive text generated.
The second section summarizes any error or attention messages that were flagged during processing. If any error or attention messages were flagged, the lines that were flagged are also listed.
The third section contains the return code issued to the operating system when CHQI ended.
Figure 56 shows an example of a listing with a number of error and attention messages.
Figure 56. Example CHQI Output Listing
TPF SIDE INFORMATION TABLE OFFLINE PROGRAM PAGE 1 LINE # |....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8| ---------+--------------------------------------------------------------------------------+ 000001 |********************************************************************** | 000002 |* * | 000003 |* SIDE INFORMATION INPUT -- A PLETHORA OF ERRORS. * | 000004 |* * | 000005 |********************************************************************** | 000006 | | 000007 |LOAD NAME=NEWINFO | ----------------------A-------------------------------------------------------------------- A. CHQI0009E INVALID LOAD PARAMETER 000008 | | 000009 |DESCR THIS TEXT WILL GET PRINTED ON THE OPERATOR'S CONSOLE | ----------A-------------------------------------------------------------------------------- A. CHQI0015E LOAD STATEMENT BEGINNING IN LINE 000007 ENDS WITHOUT SPECIFYING SS 000010 |DESCR WHEN THE OFFLINE DATA SET GETS LOADED. | 000011 | | 000012 |MODE-BATCH | ----------A-------------------------------------------------------------------------------- A. CHQI0030E NO VERB WAS SPECIFIED FOR THIS PARAMETER 000013 | | 000014 |ADD LOAD DATA | -----------------A----------B-------------------------------------------------------------- A. CHQI0007E ADD STATEMENT BEGINNING IN LINE 000014 ENDS WITHOUT SPECIFYING NAME A. CHQI0003W ADD STATEMENT BEGINNING IN LINE 000014 ENDS WITHOUT SPECIFYING TP A. CHQI0001W ADD STATEMENT BEGINNING IN LINE 000014 ENDS WITHOUT SPECIFYING LU A. CHQI0002W ADD STATEMENT BEGINNING IN LINE 000014 ENDS WITHOUT SPECIFYING MODE A. CHQI0014E LOAD MUST BE THE FIRST STATEMENT B. CHQI0015E LOAD STATEMENT BEGINNING IN LINE 000014 ENDS WITHOUT SPECIFYING SS B. CHQI0013E INVALID VERB 000015 | | 000016 |REMOVE ALL--EVERY | -----------------A---B--------------------------------------------------------------------- A. CHQI0012E INVALID REMOVE PARAMETER B. CHQI0011E INVALID PARAMETER SYNTAX 000017 | | 000018 |ADD N=M=EXPEDITE L=LU.62 T-ABC$123$ | ----------A--------B---------------C-----------D------------------------------------------- A. CHQI0032E REMOVE STATEMENT BEGINNING IN LINE 000016 ENDS WITHOUT SPECIFYING NAME B. CHQI0031E PARAMETER KEYWORD FOLLOWED BY PARAMETER KEYWORD C. CHQI0019E LU NAME MUST BEGIN WITH AN UPPERCASE LETTER D. CHQI0039E TP NAME CONTAINS HEX SUBSTRING WITH ODD NUMBER OF DIGITS 000019 | | 000020 |REMOVE NAME-SAME MODE-SLOW LU-SLOWNET.LU62 TP-ZAPMAP | -----------------------------A----------B----------------C--------------------------------- A. CHQI0005W MODE PARAMETER IS IGNORED IN REMOVE STATEMENT B. CHQI0004W LU PARAMETER IS IGNORED IN REMOVE STATEMENT C. CHQI0006W TP PARAMETER IS IGNORED IN REMOVE STATEMENT 000021 | | 000022 |ADD N-3_DOG_NIGHT L-NET@NY.LU62MAPPED T-BLANK$40$SPACE M-1SECRESP | ----------------------------A---------B-----------C-----------D-----------E---------------- A. CHQI0035E SYMBOLIC DESTINATION NAME IS LONGER THAN 8 CHARACTERS B. CHQI0026E Network ID CONTAINS INVALID CHARACTER TPF SIDE INFORMATION TABLE OFFLINE PROGRAM PAGE 2 LINE # |....+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8| ---------+--------------------------------------------------------------------------------+ C. CHQI0018E LU NAME IS LONGER THAN 8 CHARACTERS D. CHQI0038E TP NAME CONTAINS AN EMBEDDED SPACE CHARACTER E. CHQI0024E MODE MUST BEGIN WITH AN UPPERCASE LETTER 000023 | | 000024 |ADD N-MY M-DOG L-HAS T-FLEAS | 000025 | N-EVERY M-GOOD L-BOY.DOES T-FINE | ---------------A-----------B-----------C--------------------D------------------------------ A. CHQI0025E NAME IS ALREADY DEFINED FOR THIS STATEMENT B. CHQI0022E MODE IS ALREADY DEFINED FOR THIS STATEMENT C. CHQI0016E LU IS ALREADY DEFINED FOR THIS STATEMENT D. CHQI0036E TP IS ALREADY DEFINED FOR THIS STATEMENT 000026 | | 000027 |ADD N-DEST0001 M-MODEMAP1 L-TPFNET1.MAPLU1 T-RECEIVER1 | 000028 |ADD N-DEST0002 M-MODEMAP2 L-TPFNET2.MAPLU2 T-RECEIVER2 | 000029 |ADD N-DEST0003 M-MODEMAP3 L-TPFNET3.MAPLU3 T-RECEIVER3 | 000030 |ADD N-DEST0004 M-MODEMAP4 L-TPFNET4.MAPLU4 T-RECEIVER4 | 000031 |ADD N-DEST0005 M-MODEMAP5 L-TPFNET5.MAPLU5 T-RECEIVER5 | 000032 | | 000033 |REMOVE N-OBSDEST1 | 000034 |REMOVE N-OBSDEST2 | 000035 |REMOVE N-OBSDEST3 | 000036 | | 000037 |END | ----------A-------------------------------------------------------------------------------- A. CHQI0013E INVALID VERB TPF SIDE INFORMATION TABLE OFFLINE PROGRAM PAGE 3 SUMMARY SIDE INFORMATION DATA FOR ANY SUBSYSTEM 5 ADD ENTRIES WERE GENERATED 4 REMOVE ENTRIES WERE GENERATED 2 LINES OF DESCRIPTIVE TEXT WERE GENERATED 23 ERRORS WERE FLAGGED 6 WARNINGS WERE FLAGGED THE FOLLOWING LINES WERE FLAGGED: 7 9 12 14 16 18 20 22 25 37 RETURN CODE = 8 |
After you have the side information data set generated and free of errors, you can move on to steps 5, 6, and 7 listed in the beginning of Generating the Side Information Table for Mapped Conversations.
The following description refers to Figure 57, which shows a TPF console during the mounting of an offline generated side information tape, initialization of the online side information table, and loading of the tape to the side information table.
NSID0016E RECORD ID CHECK FAILURE, CHECK SIDE INFORMATION TABLE INITIALIZATION
Figure 57. Loading a Side Information Offline Generated Tape
+--------------------------------------------------------------------------------+ |User: ZTVAR A 580 | |System: CSMP0097I 11.48.39 CPU-B SS-BSS SSU-HPN IS-01 | |COTU0101I 11.48.39 TVAR BSS PROT ENTRY ACQUIRED FOR DEVICE 580 | | BY THIS PROCESSOR | |CSMP0097I 11.48.39 CPU-B SS-BSS SSU-HPN IS-01 | |COTE0001I 11.48.39 TVAR - TAPE STATUS | | | |ADDRESS TPNAME SSUNAME STATUS TPIND VOLSER DENS #BLOCKS LDR | | | | 580 AVAIL | | | |User: ZTLBL SID C LSL F$SIDOUT$ I G | |System: CSMP0097I 11.48.39 CPU-B SS-BSS SSU-HPN IS-01 | |COTL0001I 11.48.39 DTLB HPN - TAPE LABEL INFORMATION | | SID - NOT USABLE I/O-INPUT L-SL D-ALL NOCOMP | | NOBLK T - 000 | | F-SIDOUT G - S-0001 | | RETENTION PERIOD - 00007 | | LAST MOUNTED - | | LAST FILE SERIAL NO - | | | |User: ZTLBL SID U | |System: CSMP0097I 11.48.39 CPU-B SS-BSS SSU-HPN IS-01 | |COTJ0044I 11.48.39 TLBL HPN COMPLETE | | | |User: ZTMNT SID 580 AI | |System: CSMP0097I 11.48.39 CPU-B SS-BSS SSU-HPN IS-01 | |COTM0046I 11.48.39 TMNT HPN TAPE SID MOUNTED ON DEVICE 580 | | VSN A00112 G S0001 D38K SL NOBLK | +--------------------------------------------------------------------------------+
+--------------------------------------------------------------------------------+ |User: ZNSID INITIALIZE | |System: CSMP0097I 11.48.39 CPU-B SS-BSS SSU-HPN IS-01 | |NSID0004I 11.48.39 SIDE INFORMATION TABLE INITIALIZED | | | |User: ZNSID LOAD T-SID | |System: CSMP0097I 11.48.39 CPU-B SS-BSS SSU-HPN IS-01 | |NSID0037I 11.48.39 LOADING SIDE INFORMATION DATA | |CSMP0097I 11.48.39 CPU-B SS-BSS SSU-HPN IS-01 | |NSID0017I 11.48.39 USER TEXT FROM SIDE INFORMATION TAPE | |ADDING 100 ENTRIES TO SIDE INFORMATION TABLE | |--- END OF DESCRIPTION --- | |CSMP0097I 11.48.39 CPU-B SS-BSS SSU-HPN IS-01 | |NSID0005I 11.48.39 NEW SIDE INFORMATION TABLE ENTRIES LOADED | |ENTRIES PROCESSED - 100 | |ENTRIES ADDED - 100 | |ENTRIES CHANGED - 0 | |ENTRIES REMOVED - 0 | |ERRORS DURING LOAD - 0 | |CSMP0097I 11.48.39 CPU-B SS-BSS SSU-HPN IS-01 | |COTC0087A 11.48.39 TCLS HPN REMOVE SID FROM DEVICE 580 | | VSN A00112 NOBLK | |User: ZNSID D N-NAME100 | |System: CSMP0097I 11.48.39 CPU-B SS-BSS SSU-HPN IS-01 | |NSID0002I 11.48.39 SIDE INFORMATION ENTRY DISPLAY | | NAME- NAME100 | | TP- TP100 | | LU- LU100 | | MODE- MODE100 | +--------------------------------------------------------------------------------+