Specifying the I/O PCB mask

After your program issues a call with the I/O program communications block (PCB), IMS returns information about the results of the call to the I/O PCB. To determine the results of the call, your program must check the information that IMS returns.

Issuing a system service call requires an I/O PCB. Because the I/O PCB resides outside your program, you must define a mask of the PCB in your program to check the results of IMS calls. The mask must contain the same fields, in the same order, as the I/O PCB. Your program can then refer to the fields in the PCB through the PCB mask.

An I/O PCB contains the fields listed in the following table. The table describes these fields, their lengths, and which environments are applicable for each field.

Table 1. I/O PCB mask
Descriptor		Byte Length	DB/DC	DBCTL	DCCTL	DB Batch	TM Batch
Logical terminal name ¹		8	X		X
Reserved for IMS ²		2	X		X
Status code ³		2	X	X	X	X	X
8-Byte Local date and time ⁴
	Date	4	X		X
	Time	4	X		X
Input message sequence number ⁵		4	X		X
Message output descriptor name ⁶		8	X		X
Userid ⁷		8	X		X
Group name ⁸		8	X		X
12-Byte Time Stamp ⁹
	Date	4	X		X
	Time	6	X		X
	UTC Offset	2	X		X
Userid Indicator¹⁰		1	X		X
Reserved for IMS²		3

Note:

Logical Terminal Name
This field contains the name of the terminal that sent the message. When your program retrieves an input message, IMS places the name of the logical terminal that sent the message in this field. When you want to send a message back to this terminal, you refer to the I/O PCB when you issue the ISRT call, and IMS takes the name of the logical terminal from the I/O PCB as the destination.
Reserved for IMS
These fields are reserved.
Status Code
IMS places the status code describing the result of the DL/I call in this field. IMS updates the status code after each DL/I call that the program issues. Your program should always test the status code after issuing a DL/I call.

The three status code categories are:
- Successful status codes or status codes with exceptional but valid conditions. This category does not contain errors. If the call was completely successful, this field contains blanks. Many of the codes in this category are for information only. For example, a QC status code means that no more messages exist in the message queue for the program. When your program receives this status code, it should terminate.
- Programming errors. The errors in this category are usually ones that you can correct. For example, an AD status code indicates an invalid function code.
- I/O or system errors.
For the second and third categories, your program should have an error routine that prints information about the last call that was issued program termination. Most installations have a standard error routine that all application programs at the installation use.
Local Date and Time
The current local date and time are in the prefix of all input messages except those originating from non-message-driven BMPs. The local date is a packed-decimal, right-aligned date, in the format yyddd. The local time is a packed-decimal time in the format hhmmsst. The current local date and time indicate when IMS received the entire message and enqueued it as input for the program, rather than the time that the application program received the message. To obtain the application processing time, you must use the time facility of the programming language you are using.

For a conversation, for an input message originating from a program or for a message received using Multiple System Coupling (MSC), the time and date indicate when the original message was received from the terminal.
Note: Be careful when comparing the local date and time in the I/O PCB with the current time returned by the operating system. The I/O PCB date and time may not be consistent with the current time. It may even be greater than the current time for the following reasons:
- The time stamp in the I/O PCB is the local time that the message was received by IMS. If the local time was changed after the message arrived, it is possible for the current time to appear to be earlier than the I/O PCB time. This effect would be likely to occur in the hour immediately after the fall time change, when the clock is set back by one hour.
- The time stamp in the I/O PCB is derived from an internal IMS time stamp stored with the message. This internal time stamp is in Coordinated Universal Time (UTC), and contains the time zone offset that was in effect at the time the message was enqueued. This time zone offset is added to the UTC time to obtain the local time that is placed in the I/O PCB. However, the time zone offset that is stored is only fifteen minutes. If the real time zone offset was not an integer multiple of fifteen minutes, the local time passed back in the I/O PCB will differ from the actual time by plus or minus 7.5 minutes. This could cause the I/O PCB time to be later than the current time. See IMS Version 15.4 Operations and Automation for further explanation.
Concerns about the value in the local time stamp in the I/O PCB can be reduced by using the extended time stamp introduced in IMS V6. The system administrator can choose the format of the extended time stamp to be either local time or UTC. In some situations, it may be advantageous for the application to request the time in UTC from the operating system and compare it to the UTC form of the extended time stamp. This is an option available in installations where there is no ETR to keep the IMS UTC offset in sync with the z/OS® UTC offset over changes in local time.
Input Message Sequence Number
The input message sequence number is in the prefix of all input messages except those originating from non-message-driven BMPs. This field contains the sequence number IMS assigned to the input message. The number is binary. IMS assigns sequence numbers by physical terminal, which are continuous since the time of the most recent IMS startup.
Message Output Descriptor Name
You only use this field when you use MFS. When you issue a GU call with a message output descriptor (MOD), IMS places its name in this area. If your program encounters an error, it can change the format of the screen and send an error message to the terminal by using this field. To do this, the program must change the MOD name by including the MOD name parameter on an ISRT or PURG call.

Although MFS does not support APPC, LU 6.2 programs can use an interface to emulate MFS. For example, the application program can use the MOD name to communicate with IMS to specify how an error message is to be formatted.

Related reading: For more information on the MOD name and the LTERM interface, see IMS Version 15.4 Communications and Connections.
Userid
The use of this field is connected with RACF® signon security. If signon is not active in the system, this field contains blanks.

If signon is active in the system, the field contains one of the following:
- The user's identification from the source terminal.
- The LTERM name of the source terminal if signon is not active for that terminal.
- The authorization ID. For batch-oriented BMPs, the authorization ID is dependent on the value specified for the BMPUSID= keyword in the DFSDCxxx PROCLIB member:
  - If BMPUSID=USERID is specified, the value from the USER= keyword on the JOB statement is used.
  - If USER= is not specified on the JOB statement, the program's PSB name is used.
  - If BMPUSID=PSBNAME is specified, or if BMPUSID= is not specified at all, the program's PSB name is used. If PSBNAME is not defined to RACF, the Userid of the current Address Space will be used; this will be the Home Dependent Region one, or the Control Region one if LSO=Y or if PARDLI=1 has been specified for the BMP. Userid of the current Address Space will be used also if DFSBSEX0 has returned RC08.
    Related Reading: For more information about authorizing resource use in a dependent region, see IMS Version 15.4 System Administration.
Group Name
The group name, which is used by DB2® to provide security for SQL calls, is created through IMS transactions.

Three instances that apply to the group name are:
- If you use RACF and signon on your IMS system, the RACROUTE SAF (extract) call returns an eight-character group name.
- If you use your own security package on your IMS system, the RACROUTE SAF call returns any eight-character name from the package and treats it as a group name. If the RACROUTE SAF call returns a return code of 4 or 8, a group name was not returned, and IMS blanks out the group name field.
- If you use LU 6.2, the transaction header can contain a group name.
  Related reading: See IMS Version 15.4 Communications and Connections for more information on LU 6.2.
12-Byte Time Stamp
This field contains the current date and time fields, but in the IMS internal packed-decimal format. The time stamp has the following parts:

Date

yyyydddf
This packed-decimal date contains the year (yyyy), day of the year (ddd), and a valid packed-decimal + sign such as (f).

Time

hhmmssthmiju
This packed-decimal time consists of hours, minutes, and seconds (hhmmss) and fractions of the second to the microsecond (thmiju). No packed-decimal sign is affixed to this part of the time stamp.

UTC Offset

aqq$
The packed-decimal UTC offset is prefixed by 4 bits of attributes (a). If the 4th bit of (a) is 0, the time stamp is UTC; otherwise, the time stamp is local time. The control region parameter, TSR=(U/L), specified in the DFSPBxxx PROCLIB member, controls the representation of the time stamp with respect to local time versus UTC time.

The offset value (qq$) is the number of quarter hours of offset to be added to UTC or local time to convert to local or UTC time respectively.

The offset sign ($) follows the convention for a packed-decimal plus or minus sign.

Field 4 on the I/O PCB Mask always contains the local date and time. For a description of field 4, see the notes for the previous table.

Related reading: For a more detailed description of the internal packed-decimal time-format, see IMS Version 15.4 System Utilities.
Userid Indicator
The Userid Indicator is provided in the I/O PCB and in the response to the INQY call. The Userid Indicator contains one of the following:
- U - The user's identification from the source terminal during signon
- L - The LTERM name of the source terminal if signon is not active
- P - The PSBNAME of the source BMP or transaction
- O - Other name
The value contained in the Userid Indicator field indicates the contents of the userid field.