CRTDEVAPPC (Create Device Description (APPC))

CRTDEVAPPC Command syntax diagram

 

Purpose

The Create Device Description (APPC) (CRTDEVAPPC) command creates a device description for an advanced program-to-program communications (APPC) device. More information about using this command is in the Communications Configuration

book.

 

Required Parameters

DEVD

Specifies the name of the device description being created.

RMTLOCNAME

Specifies the name of the remote location. The name can contain characters A through Z, 0 through 9, $, #, or @, but the first character cannot be 0 through 9.

 

Optional Parameters

ONLINE

Specifies whether this object is automatically varied on at initial program load (IPL).

*YES: The device is automatically varied on at IPL.

*NO: This device is not automatically varied on at IPL.

LCLLOCNAME

Specifies the local location name.

Note:

The name cannot be the same as that specified for the RMTLOCNAME parameter. The combination of the LCLLOCNAME and RMTLOCNAME names must be unique for each device description attached to the same controller.

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

local-location-name: Specify the name (up to eight characters) by which the local system is known to the remote device. The name can contain characters A through Z, 0 through 9, $, #, or @, but the first character cannot be 0 through 9.

RMTNETID

Specifies the name of the remote network.

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

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

remote-network-ID: Specify the remote network ID. The name can contain characters A through Z, 0 through 9, $, #, or @, but the first character cannot be 0 through 9.

CTL

Specifies the name of the controller description to which this object is attached.

MODE

Specifies the names of the modes that define the sessions on this device.

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

mode-name: Specify no more than eight characters to specify a mode name for this device. The name may contain characters A through Z, 0 through 9, $, #, and @. The first character may not be 0 through 9. The mode name cannot be CPSVCMG or SNASVCMG; these mode names are reserved for system use. Up to 14 mode names can be specified. When APPN(*YES) and LOCADR(00) are specified on the device, no modes should be added to the device description. APPN will automatically add the modes.

MSGQ

Specifies the name of the message queue to which messages are sent. More information about using this parameter is in the Communications Management book.

*CTLD: Messages are sent to the message queue defined in the attached controller. The message queue is determined when the device is varied on.

*SYSOPR: Messages are sent to the system operator message queue (QSYS/QSYSOPR).

message-queue-name: Specify the name of the message queue to which messages are sent.

The name of the message queue 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.

LOCADR

Specifies the local location address. Specify a 2-character hexadecimal value ranging from 00 through FF.

00: The 00 value is used.

local-address: Specify the address of the location of the APPC device.

APPN

This parameter specifies whether networking is used.

*YES: Networking is used and dynamic definition of resources is allowable.

*NO: Networking is not used. Mode names cannot be added to the device while in vary on status.

SNGSSN

Specifies whether a single session using this device description will be used between the local and remote locations.

*NO: Multiple sessions are used. LOCADR(00) must be specified when SNGSSN(*NO) is specified.

Element 1: Single-Session Device Description

*YES: This device description uses single sessions.

Element 2: Number of Single-Session Conversations

10: The number of single session conversations allowed for this device description is ten.

number-of-conversations: Specify the number of conversations allowed for a single session of this device description. Valid values range from 1 through 512.

LCLCTLSSN

Specifies whether single sessions are locally or remotely controlled. *YES is valid only if SNGSSN parameter was specified as *YES.

*NO: The single session is remotely controlled.

*YES: The single session is locally controlled.

PREESTSSN

Specifies whether the single session is established automatically when the mode is started with the remote location. The value of *YES is valid only if SNGSSN(*YES) and LCLCTLSSN(*YES) are both specified.

*NO: The session is not automatically established when the mode is started.

*YES: The session is automatically established when the mode is started.

LOCPWD

Specifies the password used to validate the session establishment request.

*NONE: No password is used.

location-password: Specify the password to validate the session establishment request. An even number of hexadecimal characters must be specified. Up to 16 characters can be entered.

For example, a password consisting of the letter A would be input as C1, and an integer one would be input as F1 on the LOCPWD parameter.

SECURELOC

Specifies how security information is handled for program start requests received from remote systems. The value is sent to the remote system when sessions are established. It is used in determining how allocate or evoke requests should be built. The value only applies to conversations started with the SECURITY(SAME) level of security.

*NO: The remote system is not a secure location. Security validation done by the remote system is not accepted. SECURITY(SAME) conversations are treated as SECURITY(NONE). No security information will be sent with allocate or evoke requests.

*YES: The remote system is a secure location and the local system will accept security validation done by remote systems. For SECURITY(SAME) conversations, the local system allows the remote system to verify user passwords. On the remote system, user IDs are retrieved from the operating system. The user IDs are then sent with an already verified indicator in the allocate or evoke requests.

*VFYENCPWD: The remote system is not a secure location. For SECURITY(SAME) conversations, the remote system is not allowed to send the already verified indicator. On the remote system, user IDs and passwords are retrieved from the operating system. Passwords are then encrypted and sent with the user IDs in the allocate or evoke requests, to be verified by the local system. This value should only be used if the remote system is using OS/400 V3R2M0 or later. If the remote system does not support password protection then session establishment will not be allowed. For remote systems that support password protection, but do not support verification of encrypted passwords (VFYENCPWD), conversations will be treated as SECURITY(NONE).

AUT

Specifies the authority given to users who do not have specific authority to the device description, who are not on an authorization list, and whose user group has no specific authority to the device description.

*LIBCRTAUT: The authority for the object is the same as the create authority for QSYS. The create authority for QSYS can be displayed by using the Display Library Description (DSPLIBD) command. If the create authority is changed with the Change Library (CHGLIB) command, the new authority does not affect existing objects.

*CHANGE: The user can perform all operations on the object except those limited to the owner or controlled by object existence authority and object management authority. The user can change and perform basic functions on the object. Change authority provides object operational authority and all data authority.

*ALL: The user can perform all operations except those limited to the owner or controlled by authorization list management authority. The user can control the object's existence, specify the security for the object, change the object, and perform basic functions on the object. The user also can change ownership of the device description.

*USE: The user can perform basic operations on the device description, such as running a program or reading a file. The user cannot change the device description. *USE authority provides object operational authority, read authority, and execute authority.

*EXCLUDE: The user cannot access the device description.

authorization-list-name: Specify the name of the authorization list used.

TEXT

Specifies the text that briefly describes the device file. More information on this parameter is in Commonly used parameters.

*BLANK: Text is not specified.

'description': Specify no more than 50 characters of text, enclosed in apostrophes.

Example for CRTDEVAPPC

CRTDEVAPPC   DEVD(APPC1)  LOCADR(00)
  RMTLOCNAME(CHICAGO)  CTL(CTLAPPC01)  SNGSSN(*YES)

This command creates a device description for an APPC communications device named APPC1. The device has a location address of X'00' and is in Chicago, attached to controller CTLAPPC01. This device is limited to one session at a time.

Error messages for CRTDEVAPPC

*ESCAPE Messages

CPF261A

Device description &1 not created due to errors.

CPF2654

Device description &1 created but possibly not usable.

CPF34D7

Output queue &1 in &2 not changed due to errors.