COMM macro

The COMM macro specifies general communication requirements that are not associated with any particular terminal type. COMM is always required for terminal types that are supported by VTAM®. It is optional for BSAM, GAM, and ARAM terminal types.

The COMM macro can also be required to specify additional system options, such as support for MFS on the master terminal.

The COMM macro should be placed before the data communication specifications in the stage 1 input sequence.

This topic includes the following information:

Dynamic definition
Supported environments
Syntax
Positional parameters
Keyword parameters

Dynamic definition

General communication requirements cannot be dynamically defined.

Supported environments

The COMM macro can be used in the IMS DB/DC and DCCTL environments.

Syntax

Positional parameters

The COMM macro does not include positional parameters.

Keyword parameters

To find which parameters apply to your IMS configuration, refer to Selecting the appropriate macros to define your system.

AOEXIT=

No longer supported.

APPLID=

Specifies the application identification in the VTAM ACBs if VTAM is used. The default value is IMS.

For XRF, specify two VTAM APPLIDs: username1 and username2. These two parameters correspond to the two XRF systems. The defaults are IMS and IMS2, respectively. When MNPS is used for XRF, username1 and username2 refer to the APPLID ACBs in the two XRF systems.

All three user name values can be overridden by specifying APPLID1=, and either APPLID2= or APPLID3=, or both, in the IMS or DCC procedures. These keywords can also be specified in the DFSPBIMS or DFSPBDCC members. Username3 can match either username1 or username2, but no two APPLIDs can be active in the network at the same time.

The defaults are IMS, IMS2, and IMS3, respectively.

If NONE is specified:

The MSVERIFY program (DFSUMSV0) cannot validate that the APPLID names of the IMS system and its partner match if MSC/VTAM links are defined.
Either the job step name of the job to bring up the IMS control region is used, or the name of the started task (if a started task is used for the IMS control region) is used.

If you specify APPLID=NONE and you issue a /DIS ACTIVE DC command, the output of the command is APPLID=NONE.

APPLID=NONE cannot be specified for XRF.

COPYLOG=

Specifies the different categories of command and command response messages for which a copy is to be printed on the secondary master terminal.

If you want hardcopy logging, you must define a secondary master terminal.

The default is NONE.

NONE: Specifies that the commands listed in #ims_comm_macro__ip0i2mca52146243 and command responses from terminals are not to be printed on the secondary master terminal. The queuing for the secondary master terminal of messages not in the categories described in #ims_comm_macro__ip0i2mca52146243 is not affected by the COPYLOG statement.
MASTER: Specifies that copies of commands listed in #ims_comm_macro__ip0i2mca52146243 and command responses from the master terminal are to be printed on the secondary master terminal.
NOMASTER: Specifies that copies of the commands listed in #ims_comm_macro__ip0i2mca52146243 and command responses from terminals other than the master terminal are to be printed on the secondary master terminal.
ALL: Specifies that the commands listed in #ims_comm_macro__ip0i2mca52146243 and command responses from all terminals are to be printed on the secondary master terminal.

COPYLOG does not affect system messages, which continue to be logged to the secondary master terminal.

The commands that can be copied to the secondary master terminal are:

The following commands can be copied to the secondary master terminal:

/ACTIVATE
/ASSIGN
/CHECKPOINT
/CLSDST
/COMPT
/DBDUMP
/DBRECOVERY
/DELETE
/DEQUEUE
/DISPLAY
/IDLE
/MONITOR
/MSASSIGN
/OPNDST
/PSTOP
/PURGE
/QUIESCE
/RCLSDST
/RCOMPT
/RSTART
/START
/STOP
/TRACE
/UNLOCK SYSTEM

Other commands can be logged but are not under the control of COPYLOG as /MSVERIFY is, for example.

The COPYLOG specification can be dynamically changed at execution time by the /SMCOPY operator command.

EDTNAME=

Names the ISC edit process for LU 6.1 nodes. The name specified becomes a synonym for ISCEDT, the default name that can be input and is output on the DPN parameter of the SCHEDULER function management header. When this name is input to IMS on the DPN parameter of the ATTACH or SCHEDULER function management header, it causes IMS to use the ISC edit process. The name used on the EDTNAME parameter cannot be the same as any MFS message input descriptor (MID) name used as an input ATTACH DPN parameter to invoke an MFS process.

FESEXIT=

In IMS 15.4, this parameter is replaced by the IMS execution parameters FESEXIT and FESTIM.

Specifies whether (YES) or not (NO) the Front End Switch exit routine is to be included in the IMS nucleus.

The default is NO.

The timeout_value specifies a timeout value in seconds. A timeout_value specifies the time interval in which a reply for an FES message must be received. If no reply is received by the front-end system in time, timeout processing begins. The minimum value is 1, and the maximum value is 300.

If FESEXIT=YES is specified without a timeout value, the default for the timeout_value parameter is 30.

The FES exit routine must be placed in the data set defined by the USERLIB= keyword of the system definition IMSGEN macro before the execution of IMS stage 2 system definition. The name of the exit routine must be DFSFEBJ0.

MFSEXIT=

In IMS 15.4, this parameter is replaced by the IMS execution parameters MFSEXITF and MFSEXITS.

The variable fieldexitnum specifies the highest-numbered MFS Field Edit exit routine to be included in the generated system. fieldexitnum must be a decimal number greater than or equal to 0 and less than the default or specified value for the segmentexitnum parameter. The default is 0.

The segmentexitnum value specifies the lowest-numbered MFS Segment Edit exit routine to be included in the generated system. The segmentexitnum must be a decimal number greater than the default or specified value for the fieldexitnum parameter and less than or equal to 127. The default is 127.

Recommendation: Make lower-numbered exit routines be field exit routines, even though the lower-numbered exit routines can be segment exit routines, or can be a mixture of field and segment exit routines. An additional recommendation is that the higher-numbered exit routines be segment exit routines, although the higher-numbered exit routines can be field exit routines, or can be a mixture of field and segment exit routines.

An MFSEXIT=(14,120) specification indicates that user-supplied MFS Field Edit exit routines DFSME001 through DFSME014 and user-supplied MFS Segment Edit exit routines are IMS-supplied routines and are always included in the generated system when MFS requirements exist.

User-supplied MFS exit routines are included in the system definition-generated online control blocks module DFSIBLKx. Therefore, MFS exit routine specifications can be changed by an IMS CTLBLKS, NUCLEUS, ON-LINE, or ALL system definition. The MFSEXIT keyword specification is ignored when MFS exit requirements do not exist in the generated system.

OPTIONS=

The parameters included in this description are not position dependent within the operand sublist. If any terminal or password security options are specified here and also in the IMSGEN statement, a warning message is issued.

NOPAGE│ PAGING

Defines whether (PAGING) or not (NOPAGE) the terminal paging feature is included in the defined system. The default is NOPAGE. If 3270 or SLU 2 devices are included, or if SLU P, LU 6.1, or 3600 devices defined with MFS are included, the paging capability is automatically included.

NOTIMESTP│ TIMESTAMP

Specifies whether (TIMESTAMP) or not (NOTIMESTP) the system message time stamp feature is desired in the defined system. The default is NOTIMESTP.

When TIMESTAMP is specified, the time at which a message was generated is inserted between the message number and the message text for each message in the table.

NOMFSTEST│ MFSTEST

Specifies whether (MFSTEST) or not (NOMFSTEST) the Message Format Service test facility, MFSTEST, is to be included in the generated system. Specifying MFSTEST is invalid for systems not containing MFS terminals. The default is NOMFSTEST.

Specifying a numeric value on the COMM macro statement is no longer recommended; for compatibility reasons it is still allowed, but any numeric value is ignored. When a numeric value is specified the NOMFSTEST default is overridden and MFSTEST is set; if MFSTEST=NO is specified on the IMSGEN macro, it is also overridden.

Using MFSTEST can degrade IMS performance due to MFSTEST use of the CIOP pool.

NOFMAST│ FMTMAST

Specifies whether (FMTMAST) or not (NOFMAST) the IMS-provided support for MFS on the master terminal is to be used. This support is available for the following devices used as the master terminal:

3277 model 2
3270 displays that have a 24 x 80 screen and use symbolic names
3277 model 2 when defined as SLUTYPE2

NOUSEMSG│ USERMSGS

In IMS 15.4, these parameter are replaced by the IMS execution parameter USERMSGS.

Specifies whether (USERMSGS) or not (NOUSEMSG) the user-supplied user message tables module DFSCMTU0 is to be included within the generated system.

NOVTAUTH│ VTAMAUTH

Specifies whether (VTAMAUTH) or not (NOVTAUTH) IMS is to use the VTAM authorized path for communicating.

Related reading: Refer to ACF/VTAM Macro Language Guide for information about the authorized path facility. These parameters can be overridden by the JCL prepared for system execution.

BLKREQD | NOBLANK

Specifies whether the 1- to 8-byte transaction code requires a trailing blank. NOBLANK lets you enter a 1- to 8-byte transaction code without having to specify a trailing blank.

The selection of NOBLANK indicates that a blank does not have to be specifically entered after a one- to eight-byte transaction code, but if data is being included after the transaction code, then a blank must be inserted between the code and the data.

PASSWD=

Specifies, when XRF is not used, that one password is to be specified in the VTAM ACB.

This password is checked by VTAM. If no password is specified, either in the VTAM ACB or in the PASSWD1= parameter, and VTAM requires one (during VTAM system definition), the IMS VTAM ACB is not initialized.

For XRF, you should specify two VTAM passwords that correspond to the two XRF systems. If only one password is specified, it is used as the password for both XRF systems.

RECANY=

This parameter is required only when defining VTAM terminals. It defines the number and size of the RECEIVE ANY buffers.

This keyword and its parameters are optional and can be either overridden with execution-time parameters or defaults can be used if not specified by either of these methods.

number

Specifies the number of VTAM RECEIVE ANY buffers to be present in the IMS system. Valid values are from 1 to 500. The default is 16 if not specified during system definition or with execution-time parameters. You can override this specification with the EXEC parameter RECA= in the IMS procedure.

When MNPS is used for XRF, this parameter specifies the number of buffers for the MNPS ACB. IMS automatically allocates one additional buffer for the APPLID ACB.

Specifying too many buffers does not improve performance and can result in excessive resource consumption, especially high CPU utilization. You can check current and maximum use by looking in the X'450D' log record.

size

Specifies the size of the largest RECEIVE ANY buffer. This size must be large enough to handle maximum input from any VTAM-attached terminal. The minimum acceptable size is 50; the maximum is 30720. The default is 1920 if not specified during system definition or with execution-time parameters. The resulting usable input buffer size for any terminal can be calculated as follows for the devices shown:

3601: Size is record size plus header. The header size is 2 bytes if MFS is not used and 11 bytes if MFS is used.

3270: Size is the input data stream length. The minimum size is 300 bytes and a reasonable maximum size is 3842 bytes.

SLU 1, SLU 2: Record size should be equal to or greater than the largest input record to be received.

SLU P: Size is record size plus header. The header size is 5 bytes if MFS is not used and variable from 7 bytes to 40 bytes if MFS is used.

LU 6.1: Size is record size plus header. The header size without MFS is variable from 0 bytes to 45 bytes. The header size with MFS is variable from 17 bytes to 52 bytes.

NTO: Record size should be equal to or greater than the largest input record to be received.

For all VTAM terminals, the RECANY buffer size must be a decimal value that can be expressed by the algorithm X times 2 to the power of Y. X must be a value from 8 through 15, and Y must be a value from 3 through 11. This is a VTAM restriction. Thus, for example, the value 144 (representing 9x2⁴) or the value 28672 (representing 14x2¹¹) are acceptable values.

Related reading: Details of this VTAM restriction are in z/OS® V1R2 Communications Server: SNA Programming.

These are valid VTAM buffer sizes. This restricts the valid VTAM buffer sizes to one of the following decimal values:

112
120
128
144
160
176
192
208
224
240
256
288
320
352
384
416
448
480
512
576
640
704
768
832
896
960
1024
1152
1280
1408
1536
1664
1792
1920
2048
2304
2560
2816
3072
3328
3584
4096
4608
5120
5632
6144
6656
7168
7680
8192
9216
10240
11264
12288
13312
14336
15360
16384
18432
20480
22528
24576
26624
28672
30720

IMS converts the specified decimal value to the format required for the bind parameter fields and places the value into the appropriate field in the bind parameter list. If the maximum request unit (RU) value specified cannot be converted exactly into the bind format, the value is rounded down to the next-lower value bind format for inbound RUs and rounded up to the next-higher value bind format for outbound RUs.

SECCNT=

Specifies the maximum number of terminal and password security violations to be accepted per physical terminal before master terminal notification of such violation. The default is 0, which nullifies notification of the master terminal. The number specified can be 0, 1, 2, or 3. This value is reset to 0 upon successful signon and does not continue across transactions.

If SECCNT is not 0, the master terminal is notified for every violation.

SIMEXIT=

In IMS 15.4, this parameter is replaced by the IMS execution parameter SIMEXIT.

Specifies whether (YES) or not (NO) the Shared Printer Message Router exit routine is to be included in the IMS nucleus.

This exit routine must be placed in the data set defined by the USERLIB= keyword of the system definition IMSGEN macro statement before the execution of stage 2. The name of the exit routine must be DFSSIML0. A default exit routine is not provided.

The exit routine is bypassed unless SIMEXIT=YES is specified. If SIMEXIT=YES is specified, the exit routine DFSSIML0 is called when a message is queued for terminals defined with OPTIONS=SHARE on the TERMINAL macro statement.

When SIMEXIT=NO, the default, the router module assumes that /OPN is always simulated when output is enqueued for a terminal defined as OPTIONS=SHARE on the TERMINAL macro statement. Even if SIMEXIT=NO is specified, the module DFSSIML0 can be manually bound into the nucleus.

Usage information

The keyword parameters that follow are no longer used by the COMM macro; if they are specified, they are ignored:

NOPSWD, PASSWD, FORPSW
NOTERMNL, TERMINAL, FORCTERM
NOMSPEX, MSPEXIT
NOMSLEX, MSLEXIT