CHGICFDEVE (Change ICF Program Device Entry)

CHGICFDEVE Command syntax diagram

 

Purpose

The Change Intersystem Communications Function Program Device Entry (CHGICFDEVE) command changes the attributes of the specified program device entry in the specified Intersystem Communications Function (ICF) file.

 

Required Parameters

FILE
Specifies the qualified name of the ICF file for which the ICF program device entry is being changed.

The name of the ICF file can be qualified by one of the following library values:

*LIBL: All libraries in the job's library list are searched until the first match is found.

*CURLIB: The current library for the job is searched. If no library is specified as the current library for the job, the QGPL library is used.

library-name: Specify the name of the library to be searched.

file-name: Specify the name of the file that contains the program device entry to be changed.

PGMDEV
Specifies the program device entry name in the ICF file whose attributes are being changed. The program device entry must exist in the specified ICF file.

 

Optional Parameters

RMTLOCNAME
Specifies the remote location name of the system with which this object communicates.

More information on how the system uses the RMTLOCNAME parameter to select an APPC device description is in APPC, APPN, and HPR.

*SAME: The value does not change.

*REQUESTER: The name used to refer to the communications device through which the program is started is used. The session that is assigned when the program device is acquired is the same session in which the program start request is received. If the program is not started as a result of a program start request, the acquire operation of the program device fails. The target program uses *REQUESTER as the remote location name in the intersystem communications function (ICF) file to connect to the session that the source program used to send the program start request.

The *REQUESTER value can be specified on only one program device entry and is valid only for a target communication job. If *REQUESTER is specified in any other type of job, a message is sent.

remote-location-name: Specify the full name of a remote location. The remote location need not exist at the time this command is run, but must exist (be configured on the system as a device description or in the advanced peer-to-peer networking (APPN) system for this remote location) when the program acquires the program device. This value cannot be specified with CNVTYPE(*SRCPGM).

CMNTYPE
Specifies which types of communications parameters show on the prompt screen. This parameter is used only for prompting purposes. The value specified for this parameter determines the subset of other parameters that are shown (prompted) for the user.

*ALL: The parameters for all of the communications types appear in the prompt.

*APPC: The advanced program-to-program communications (APPC) parameters appear in the prompt.

*ASYNC: The asynchronous (ASYNC) parameters appear in the prompt.

*BSCEL: The binary synchronous communications equivalence link (BSCEL) parameters appear in the prompt.

*FINANCE: The finance parameters appear in the prompt.

*INTRA: The intrasystem (INTRA) parameters appear in the prompt.

*RETAIL: The retail parameters appear in the prompt.

*SNUF: The SNA upline facility (SNUF) parameters appear in the prompt.

DEV
Specifies the communications device used in the remote location. This parameter can only be specified for APPC, FINANCE, RETAIL, INTRA, and SNUF communications types.

More information on how the system uses the DEV parameter to select an APPC device description is in APPC, APPN, and HPR.

*SAME: The value does not change.

*LOC: The device associated with the remote location is used. If several devices are associated with the remote location, the system determines which device is used.

device-name: Specify the name of a communications device associated with the remote location. If the device name is not valid for the remote location, a message is sent when the program device entry is acquired. More information on device names is in APPC, APPN, and HPR.

LCLLOCNAME
Specifies the local location name.

This parameter applies to the APPC communications type only and is ignored for all other communications types.

More information on how the system uses the LCLLOCNAME parameter to select an APPC device description is in APPC, APPN, and HPR.

*SAME: The value does not change.

*LOC: The device associated with the remote location is used. If several devices are associated with the remote location, the system determines which device is used.

*NETATR: The LCLLOCNAME value specified in the system network attributes is used.

local-location-name: Specify the local location name associated with the program device entry. The local location name is specified only in APPC to indicate a specific local location name for the remote location. If the local location name is not valid for the remote location, or for the remote location and device, an escape message is sent when the program device entry is acquired.

MODE
Specifies the mode name used. This parameter applies only to the APPC communications type and is ignored for all other communication types.

*SAME: The value does not change.

*NETATR: The mode name specified in the network attributes is used.

*BLANK: The mode name consisting of 8 blank characters is used.

mode-name: Specify a mode name for the APPC communications device. If the mode name is not valid for any combination of remote location device, local location, and remote network ID, an escape message is sent when the program device entry is acquired.

RMTNETID
Specifies the remote network identifier (ID) used with the remote location. This parameter applies to the APPC communications type only and is ignored for all other communications types.

More information on how the system uses the RMTNETID parameter to select an APPC device description is in APPC, APPN, and HPR.

*SAME: The value does not change.

*LOC: The remote network identifier (ID) associated with the remote location is used. If several remote network IDs are associated with the remote location, the system determines which remote network ID is used.

*NETATR: The RMTNETID value specified in the system network attributes is used.

*NONE: No remote network identifier (ID) is used.

remote-network-ID: Specify a remote network ID for the APPC communications device.

FMTSLT
Specifies the record format selection used for input operations.

*SAME: The value does not change.

*PGM: The program determines which record formats are selected. If an input (read) operation with a record format name is specified, that format is selected. If an input operation without a record format is specified, the default format (the first record format in the file) is selected. This also means that if there are any record identification (RECID) parameters specified in the data description specifications (DDS) for the file, or if any remote formats are received, they are not taken into consideration when the record is selected.

*RECID: The record identification (RECID) keywords specified in the DDS for the file are used for record selection. If there are no RECID keywords in the file, an error message is sent, the acquire operation of the program device ends, and the device is not acquired.

*RMTFMT: The remote format names received from the sending system are used for record selection. If the device is not an APPC or INTRA device and *RMTFMT is specified, a run time error occurs when the program device entry is acquired.

APPID
Specifies (in characters) the Virtual Telecommunications Access Method (VTAM) identifier (ID) of the Customer Information Control System for Virtual Storage (CICS/VS) or Information Management System/Virtual Storage (IMS/VS) host subsystem sent with the sign-on message. This parameter applies to the SNUF communications type only and is ignored for all other communications type.

*SAME: The value does not change.

*DEVD: The application identifier specified in the device description is sent without the sign-on message.

*USER: The application program can send messages or a logon to the host. This is valid only when using the 3270 program interface.

application-ID: Specify the application identifier sent with the sign-on message.

BATCH
Specifies, for both CICS/VS and IMS/VS, whether this session is used for batch jobs. This parameter applies to the SNUF, RETAIL and INTRA communications types only and is ignored for all other communications types.

*SAME: The value does not change.

*NO: Batch jobs do not occur.

*YES: Batch jobs occur.

HOST
Specifies the host or remote subsystem with which this session communicates. This parameter applies to the SNUF communications type only and is ignored for all other communications types.

*SAME: The value does not change.

*DEVD: The host system specified in the device description is used.

*CICS: The session communicates with CICS/VS.

*IMS: The session communicates with IMS/VS.

*IMSRTR: The session communicates with IMS/VS using the ready-to-receive option.

ENDSSNHOST
Specifies how SNUF ends the session with the host. This parameter is valid only for SNUF communications.

*SAME: The value does not change.

*RSHUTD: SNUF sends a request-shut-down command to the host.

*TERMSELF: SNUF sends a terminate-self command to the host. It may be necessary to specify this value if the value *RSHUTD fails to end a session with a non-IBM host.

SPCHOSTAPP
Specifies whether SNUF customizes support for special host applications outside the CICS or IMS application layer.

*SAME: The value does not change.

*DEVD: The special host application specified in the device description is used.

*NONE: SNUF does not customize support for special host applications.

*FLASH: SNUF customizes support for the Federal Link Access for Secondary Half-sessions (*FLASH) protocol application.

INZSELF
Specifies whether a formatted INIT-SELF is built in place of the unformatted sign-on normally sent by SNUF to the host.

*SAME: The value does not change.

*NO: The unformatted default sign-on provided by SNUF is used.

*YES: The formatted INIT-SELF provided by SNUF is used.

HDRPROC
Specifies, for both CICS/VS and IMS/VS, whether received function management headers are passed to the application program. This parameter applies to the SNUF communications type only and is ignored for all other communications types.

*SAME: The value does not change.

*SYS: SNA upline facility (SNUF) removes function management headers before passing data to the program.

*USER: Function management headers are passed with the data to the program.

MSGPTC
Specifies, for both CICS/VS and IMS/VS, whether message protection is used for this session. This parameter applies to the SNUF communications type only and is ignored for all other communications types.

*SAME: The value does not change.

*YES: Message protection is used. SNUF saves messages until they are responded to and tries synchronization again if errors occur. *YES is valid only when BATCH(*NO) is also specified.

*NO: Message protection is not used.

EMLDEV
Specifies that the program device entry is used to send and receive data streams to and from specific types of 3270 display or printer devices being emulated. This parameter consists of an emulation device type and an emulation device data format. The emulation device data format specifies the format of the type 3270 data stream being sent or received. A 20- or 32-byte common header that contains type 3270 command and data flow information is located at the start of the I/O buffer that is sending or receiving the type 3270 data stream. This parameter applies to the SNUF communications type only. This parameter can be specified as a list of two values (elements) or as a single value (*NONE).

Element 1: Type of Device

*SAME: The value does not change.

3278: The data stream is for a 3279, 3278, or 3277 display device.

3284: The data stream is for a 3284 printer.

3286: The data stream is for a 3286 printer.

3287: The data stream is for a 3287 printer.

3288: The data stream is for a 3288 printer.

3289: The data stream is for a 3289 printer.

Element 2: Format of the Data Stream

*SAME: The value does not change.

*UNFORMAT: An unformatted 3270 data stream is sent or received. The application program must translate the data stream into a display or printer image.

*FIELD: A formatted 3270 data stream is sent or received. The formatted 3270 data stream contains a display or printer image followed by field definitions. The field definitions indicate the location and characteristics of each field.

*NOFIELD: A formatted 3270 data stream that has no field definitions but contains a display or printer image is sent or received.

*EXTFIELD: A formatted 3270 data stream contains extended field attribute information. The extended field attribute information is in the field definitions which follow the display image. The field definitions indicate the location and characteristics of each field. The value *EXTFIELD is valid only when 3278 is specified for the type of device on the EMLDEV parameter.

Note: If *FIELD, *NOFIELD, or *EXTFIELD is specified, BATCH(*NO) must also be specified.

Other Single Values

*NONE: This program device entry is not used for sending and receiving 3270 data streams.

CNVTYPE
Specifies the conversation type for which the application program is designed. This parameter only applies to the APPC communications type, and is ignored for all other communications types.

More information on the APPC communications type is in APPC, APPN, and HPR.

*SAME: The value does not change.

*SYS: The advanced program-to-program communications (APPC) mapped conversation support is used.

*USER: The advanced program-to-program communications (APPC) basic conversation support is used.

*SRCPGM: The target program accepts the conversation type specified by the source program. If this value is specified, RMTLOCNAME(*REQUESTER) must also be specified.

BLOCK
Specifies whether the system or the user controls whether records are combined into blocks when they are sent. This parameter applies to the BSCEL communications type only and is ignored for all other communications types.

With this parameter, one of the following conditions of record formatting can be specified:

  • No blocking or deblocking: The record format described in the DDS is the format used for both the record and the block.

  • User blocking and/or deblocking: Give the BSC controls needed to describe the record format of the system.

  • System blocking with record separator characters: Specify the record separator character used by the system to determine record boundaries in the block.

  • System blocking of fixed-length records: The system uses fixed-length records, and blocks and/or deblocks them accordingly.

If a parameter value other than *NONE or *USER is specified, records are blocked as required by the system for output and are deblocked on input.

Element 1: Blocking Option

*SAME: The value does not change.

*DEVD: The block option specified in the device description is used.

*NONE: Blocking or deblocking is not done by the system.

*ITB: The records are blocked or deblocked based on the location of an intermediate text block (ITB) control character. For input files, a record is delimited by locating the next intermediate text block character. An end-of-text or end-of-transmission block character is used as an intermediate text block character to delimit a block. For output files, an ITB character is added after the record. If it is the last character of the block, the ITB is replaced by an end-of-text or end-of-transmission block character.

*IRS: The records are blocked or deblocked based on the location of an interrecord separator (IRS) character. For input files, a record is delimited by locating the next IRS character. For output files, an IRS character is added after the record.

*NOSEP: No record separator character is contained in the transmission block sent to or received from the device. The system blocks and deblocks the records by using a fixed-length record, as specified in the DDS format specifications.

*USER: The program provides all the control characters (including record separator characters, binary synchronous communications (BSC) framing characters, and transparency characters) necessary to send records. More information about the device and binary synchronous communications equivalence link (BSCEL) support characteristics is in the BSC Equivalence Link Programming

book.

*SEP: The records are blocked or deblocked, based on the location of a record separator character that is specified by the user. For input files, a record is delimited by locating the next record separator character. For output files, a record separator character is added following the record.

Element 2: Record Separator

X '1E': The record separator character X '1E' is used.

record-separator-character: Specify a unique 1-byte record separator character. The record separator character can be specified as 2 hexadecimal characters, as in BLOCK(*SEP X'FD'), or as a single character by specifying a value ranging from 0 through 9 or A through Z, as in BLOCK(*SEP A).

The following are BSC control characters that cannot be used as record separator characters:

Table 1. Characters Unavailable for Record Separators (Used for BSC Control)

EBCDIC ASCII BSCEL Control
X'01' X'01' SOH (start-of-header)
X'02' X'02' STX (start-of-text)
X'03' X'03' ETX (end-of-text)
X'10' X'10' DLE (data-link escape)
X'1D' X'1D' IGS (interchange group separator)
X'1F' X'1F' ITB (intermediate text block)
X'26' X'17' ETB (end-of-transmission block)
X'2D' X'05' ENQ (enquiry)
X'32' X'16' SYN (synchronization)
X'37' X'04' EOT (end-of-transmission)
X'3D' X'15' NAK (negative acknowledgment)

RCDLEN
Specifies the maximum record length (in bytes) for data sent and received. This parameter applies to the BSCEL and the SNUF communications types only and is ignored for all other communications types.

*SAME: The value does not change.

*DEVD: The record length specified in the device description is used. If a record is longer than the specified record length, a run time error occurs when the record is sent or received.

record-length: Specify the maximum record length (in bytes) to use with this device file. The value must be at least the size of the largest record sent. If a record is longer than the specified record length, a run time error occurs when the record is sent or received. Valid values range from 1 through 32767 bytes for SNUF communications. For BSCEL communications, the maximum record length is 8192 bytes.

BLKLEN
Specifies the maximum block length (in bytes) for data sent. This parameter applies to the BSCEL and the SNUF communications types and is ignored for all other communications types.

*SAME: The value does not change.

*DEVD: The block length specified in the device description is used.

block-length: Specify the maximum block length (in bytes) of records sent. The value must be at least the size of the largest record sent. Valid values range from 1 through 32767 for SNA upline facility (SNUF). For binary synchronous communications equivalence link (BSCEL) communications, the maximum block length is 8192.

TRNSPY
Specifies whether data is sent in transparent text mode. Transparent text mode allows all 256 extended binary-coded decimal interchange code (EBCDIC) character codes to be sent. Use this function when sending packed or binary data fields. This parameter applies to the BSCEL communications type only and is ignored for all other communications types.

*SAME: The value does not change.

*DEVD: The text transparency option specified in the device description is used.

*NO: Text transparency is not used.

*YES: Text transparency is used, which permits the transmission of all 256 EBCDIC character codes. *YES is valid only when BLOCK(*NONE), BLOCK(*NOSEP), or BLOCK(*USER) is specified.

Note: Transparency of received data is determined by the data stream; therefore, this parameter is not relevant for received data. If TRNSPY(*YES) is specified with BLOCK(*USER), the BSCEL communications type ignores the transparency indicator during write operations. Correct controls must be given with the data to get transparent transmission of data. For example, the data-link escape (DLE) and start-of-text (STX) character control characters must first be specified; the system gives the remaining control characters for transparent sending of data.

DTACPR
Specifies whether data compression is performed.

Note: DTACPR(*YES) cannot be specified if TRNSPY(*YES) is specified. This parameter applies to the BSCEL communications type only and is ignored for all other communications types.

*SAME: The value does not change.

*DEVD: The data compression option specified in the device description is used.

*NO: No data compression or decompression occurs.

*YES: Data is compressed for output and decompressed for input.

TRUNC
Specifies whether trailing blanks are removed from output records. This parameter is for the BSCEL communications type only and is ignored for all other communications types.

*SAME: The value does not change.

*DEVD: The truncation option specified in the device description is used.

*NO: Trailing blanks are not removed from output records.

*YES: Trailing blanks are removed from output records.

Note: TRUNC(*YES) cannot be specified if BLOCK(*NOSEP) or BLOCK(*ITB) is specified. If TRUNC(*YES) is specified when DTACPR(*YES) or BLOCK(*USER) is specified, then truncation is ignored.

OVRFLWDTA
Specifies whether overflow data is discarded or retained.

*SAME: The value does not change.

*DISCARD: Overflow data is not kept.

*RETAIN: Overflow data is kept.

GRPSEP
Specifies a separator for groups of data (for example, data sets and documents). This parameter applies to the BSCEL communications type only and is ignored for all other communications types.

*SAME: The value does not change.

*DEVD: The group separator option specified in the device description is used.

*DEV3740: A null record (STXETX) is used as a data group separator.

*EOT: An end-of-transmission (EOT) BSC control character is used as a data group separator.

*OFCSYS: A block sent that ends with the BSC control character ETX (end-of-text) is used as a data group separator.

RMTBSCEL
Specifies the type of BSCEL session with the remote system. This parameter applies to the BSCEL communications type only and is ignored for all other communications types.

*SAME: The value does not change.

*DEVD: The RMTBSCEL option specified in the device description is used.

*NO: The remote system cannot recognize BSCEL commands or messages. In most cases, *NO is used when communicating with remote systems such as a 3741 Data Entry Station, an Office System 6, a 5230 Data Collection System, or a System/38.

*YES: The remote system can recognize the BSCEL transaction starting commands, transaction ending commands, and online messages. In most cases, *YES indicates that the remote system is another iSeries 400, System/38, System/36, or a System/34 with BSCEL support.

INLCNN
Specifies the method used to make a connection on the line for the session being acquired. This parameter applies to the binary synchronous communications equivalence link (BSCEL) communications types only.

*SAME: The value does not change.

*CTLD: The initial connection value specified in the controller description is used.

*ANS: The remote system starts the call and the local system answers the call.

*DIAL: The local system starts the call.

Examples for CHGICFDEVE

Example 1: Changing the Record Format Selection 

CHGICFDEVE  FILE(ICFTEST)  PGMDEV(BSCEL2)
  RMTLOCNAME(BSCNYC)  FMTSLT(*RECID)

This command changes the program device entry named BSCEL2 in ICF file ICFTEST. The program device is changed to attributes of FMTSLT(*RECID). The remote location name is changed to BSCNYC.

Example 2: Changing the Conversation Type 

CHGICFDEVE  FILE(QGPL/ICF1)  PGMDEV(APPC1)
  RMTLOCNAME(*REQUESTER)
  FMTSLT(*RMTFMT)  CNVTYPE(*SYS)

This command changes the program device entry named APPC1 in ICF file ICF1 to have the remote location name *REQUESTER. This program device entry is changed to the FMTSLT(*RMTFMT) and CNVTYPE(*SYS) attributes.

Example 3: Changing the Communications Device 

CHGICFDEVE  FILE(ICFLIB/ICFAPPL1)  PGMDEV(APPC)
  RMTLOCNAME(APPCMPLS)  DEV(MPLSLINE2)

This command changes the program device entry named APPC in file ICFAPPL1. The remote location name is changed to APPCMPLS and the device is changed to MPLSLINE2.

Error messages for CHGICFDEVE

*ESCAPE Messages

CPF7367
Device not changed in file &1 in &2.