List Configuration Descriptions (QDCLCFGD) API

The List Configuration Descriptions (QDCLCFGD) API returns a list of configuration descriptions. The list elements are all of one type (such as line, controller, or device). The list contents can be further restricted by one or more qualifiers, specified as parameters.

The QSYS2.MEDIA_LIBRARY_INFO view can be considered as an alternative to this API. See MEDIA_LIBRARY_INFO view for more information.

Authorities and Locks

Configuration Description Authority

*USE

User Space Authority

*CHANGE

User Space Library Authority

*EXECUTE

(If one or more listed objects do not meet the authority requirement, they will be omitted from the returned list. Only objects to which the user has proper authority are in the list.)

Required Parameter Group

Qualified user space name

INPUT; CHAR(20)

The user space that receives the information, and the library in which it is located. The user must have read/write access to this space. The first 10 characters contain the user space name, and the second 10 characters contain the library name.

You can use these special values for the library name:

*CURLIB	The job's current library
*LIBL	The library list

Format name

INPUT; CHAR(8)

The content and format of the list returned. The possible format names are:

CFGD0100	List of selected configuration descriptions
CFGD0200	List of selected configuration descriptions, plus current status of each one

See Format of Configuration Lists for a description of these formats.

Configuration description type

INPUT; CHAR(10)

The type of configuration descriptions to be included in the list. The possible description types are:

*LIND	Line descriptions
*CTLD	Controller descriptions
*DEVD	Device descriptions
*NWID	Network interface descriptions
*NWSD	Network server descriptions
*NTBD	NetBIOS descriptions
*IPXD	Internetwork Packet Exchange (IPX) descriptions

Object qualifier

INPUT; CHAR(40)

A restriction on the objects to be listed. If a qualifier is specified that is inconsistent with the configuration description type parameter, an error message is returned. A null list is returned if no configuration descriptions meet the qualifications. If this parameter is set to all blanks, no object qualification is performed. This parameter is divided into four 10-character fields.

The primary qualifier value is placed in the first 10 characters of the parameter. The allowable values are:

Object name	Object of this name only, of the specified configuration description type
Generic object name	All objects that have names matching the generic string, of the specified configuration description type
*ALL	All objects of the specified configuration description type
*APPC	APPC controllers and devices only
*ASP	Auxiliary storage pool devices only
*ASYNC	Asynchronous lines, controllers, and devices only
*ATM	Asynchronous transfer mode network interfaces only
*BSC	BSC lines, controllers, and devices only
*CMN	Communications controllers or devices only
*CRP	Cryptographic devices only
*DDI	Distributed data interface lines only
*DKT	Diskette devices only
*DSP	Display devices only
*ELAN	Ethernet lines only
*ETHBRG	Bridged Ethernet lines only
*FAX	Fax lines only
*FNC	Finance controllers and devices only
*FR	Frame relay network interfaces and lines only
*HOST	Host controllers and devices only
*IDLC	IDLC lines only
*INTRA	Intrasystem devices only
*ISDN	Integrated Services Digital Network (ISDN) network interfaces only
*LANPRT	LAN printer devices only
*LCLDSP	Local display devices only
*LCLPRT	Local printer devices only
*LOC	Devices that match the specified remote location name only
*LWS	Local work station controllers only
*MLB	Media library devices only
*NET	Network lines, controllers, or devices only
*NWSH	Network server host adapter devices only
*OPT	Optical devices only
*OPTICAL	All optical devices and optical media library devices (equivalent to *OPT plus *OPTMLB)
*OPTMLB	Optical media library devices only
*PPP	Point-to-point lines only
*PRT	Printer devices only
*RMTDSP	Remote display devices only
*RMTPRT	Remote printer devices only
*RSRC	Network interfaces, lines, controllers, or devices that match the specified resource name only
*RTL	Retail controllers and devices only
*RWS	Remote work station controllers only
*SDLC	SDLC lines only
*SNPT	SNPT devices and SNPT-class devices only (SNPT-class devices include printer, display, finance, and retail devices)
*SNUF	SNA upline facility devices only
*T1	Network interface of type T1.
*TAP	Tape devices and controllers only
*TAPE	All tape devices and tape media library devices (equivalent to *TAP plus *TAPMLB)
*TAPMLB	Tape media library devices only
*TDLC	TDLC lines only
*TRLAN	Token-ring lines only
*VWS	Virtual work station controllers only
*VRTDSP	Virtual display devices only
*VRTPRT	Virtual printer devices only
*WLS	Wireless lines only
*WS	Work station controllers only
*X25	X.25 lines only

The information in the following tables describes the requirements for the first (primary qualifier), second, third, and fourth 10 characters of this parameter.

If...	Then...
Configuration description type parameter is *NWSD and the primary qualifier equals an object name	The last 2 characters of the 10-character primary qualifier must be blanks
Note: This is because network server names can only be up to 8 characters.

If...	Then...
Configuration description type parameter is *NWSD	Primary qualifier must be specified as only *ALL, *RSRC, or an object name
Configuration description type parameter is *NTBD	Primary qualifier must be specified as only *ALL or an object name
Configuration description type parameter is *IPXD	Primary qualifier must be specified as only *ALL or an object name

If...	Then...
Configuration description type parameter is *DEVD and primary qualifier is *LOC	Remote location name to be used is placed in second 10 characters
Note: If a remote location name is specified with any other combination of the configuration description type parameter and primary qualifier, an error message is returned.

If...	Then...
Primary qualifier is *RSRC	Resource name to be used is placed in second 10 characters
Note: If a resource name is specified with any other primary qualifier, an error message is returned.

If...	Then...
Configuration description type parameter is *CTLD or *DEVD	Type qualifier value may be placed in third 10 characters
Note: If a type qualifier is specified with any other value for the configuration description type parameter, an error message is returned. A list of valid type values can be found in the Local Device Configuration manual. If the type value is not valid, a null list is returned.

If...	Then...
Configuration description type parameter is *CTLD or *DEVD and type qualifier is coded in third 10 characters	Model qualifier value may be placed in fourth 10 characters
Note: If a model qualifier value is specified with any other value for the configuration description type parameter or if the type qualifier is blank, an error message is returned. A list of valid model values can be found in the Local Device Configuration manual. If the model value is not valid, a null list is returned.

Status qualifier

INPUT; CHAR(20)

A logical operator and a status value that are used to qualify which configuration descriptions are included in the list. The first 10 bytes contain a logical operator, left-justified. The valid values for the logical operator are:

*GT	Greater than
*GE	Greater than, or equal to
*LT	Less than
*LE	Less than, or equal to
*EQ	Equal to
*NE	Not equal to

The second 10 bytes contain a value denoting status, left-justified. The allowed status values, in order of precedence, are:

*ACTIVE	Object is active.
*VARYON	Object is varied on.
*VARYOFF	Object is varied off.

The value in the second 10 bytes has an inherent hierarchy: *ACTIVE is "greater than" *VARYON, and *VARYON is "greater than" *VARYOFF. The two values are used together to form a logical qualifier. For example, "*GE       *VARYON    " causes only objects that are active or varied on to be listed. Objects that are currently varied off are excluded. Both values must be present if either is present. An invalid logical qualifier results in a null list being returned. This qualifier must be blank if the configuration description type parameter is *NTBD or *IPXD.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

Format of Configuration Lists

To request a list of configuration descriptions of a specific type, use format CFGD0100. To request the current status for each description returned, use format CFGD0200.

The configuration description list consists of:

• A user area
• A generic header
• An input parameter section
• A header section
• A list data section:
  • CFGD0100 format
  • CFGD0200 format

For details about the user area and generic header, see User spaces. For details about the remaining items, see the following sections. For detailed descriptions of the fields in the list returned, see Field Descriptions.

When you retrieve list entry information from a user space, you must use the entry size returned in the generic header. The size of each entry may be padded at the end. If you do not use the entry size, the result may not be valid. For examples of how to process lists, see Examples: APIs and exit programs.

Input Parameter Section

Offset		Type	Field
Dec	Hex
0	0	CHAR(10)	User space name specified
10	A	CHAR(10)	User space library name specified
20	14	CHAR(8)	Format name specified
28	1C	CHAR(10)	Configuration description type specified
38	26	CHAR(40)	Object qualifier specified
78	4E	CHAR(20)	Status qualifier specified
98	62	CHAR(2)	Reserved

Header Section

Offset		Type	Field
Dec	Hex
0	0	CHAR(10)	Configuration description type used
10	A	CHAR(40)	Object qualifier used
50	32	CHAR(20)	Status qualifier used
70	46	CHAR(2)	Reserved
72	48	CHAR(10)	User space name used
82	52	CHAR(10)	User space library name used

CFGD0100 Format

Offset		Type	Field
Dec	Hex
0	CHAR(10)		Configuration description name
10	A	CHAR(10)	Configuration description category
20	14	CHAR(8)	Retrieve API format name
28	1C	CHAR(4)	Configuration description command suffix

CFGD0200 Format

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Current status: numeric code
4	4	CHAR(10)	Configuration description name
14	E	CHAR(10)	Configuration description category
24	18	CHAR(20)	Current status: displayable text
44	2C	CHAR(50)	Text description
94	5E	CHAR(10)	Job name
104	68	CHAR(10)	User name
114	72	CHAR(6)	Job number
120	78	CHAR(10)	Pass-through device
130	82	CHAR(8)	Retrieve API format name
138	8A	CHAR(4)	Configuration description command suffix
142	8E	CHAR(7)	Last activity date

Field Descriptions

Configuration description name. The name of an object selected for inclusion in the list.

Configuration description category. The value returned in this field depends on the value specified for the configuration description type parameter when the API was called, as follows:

• Line description

  If the configuration description type parameter is *LIND (line description), the value is one of the following.

  Note: The Retrieve Line Description (QDCRLIND) API can be used to retrieve detailed information about the configuration description. Use a format name shown in the following table as input when you call the QDCRLIND API.

  Line Description Category	Line Description API Format Name	Line Description Command Suffix
  *ASYNC	LIND0300	ASC
  *BSC	LIND0400	BSC
  *DDI	LIND1200	DDI
  *ELAN	LIND0500	ETH
  *FAX	LIND1400	FAX
  *FR	LIND1300	FR
  *IDLC	LIND0600	IDLC
  *NET	LIND0700	NET
  *PPP	LIND1600	PPP
  *SDLC	LIND0800	SDLC
  *TDLC	LIND0900	TDLC
  *TRLAN	LIND1000	TRN
  *WLS	LIND1500	WLS
  *X25	LIND1100	X25

  
  
  
• Controller description

  If the configuration description type parameter is *CTLD (controller description), the value is one of the following:

  Note: The Retrieve Controller Description (QDCRCTLD) API can be used to retrieve detailed information about the configuration description. Use a format name shown in the following table as input when you call the QDCRCTLD API.

  Controller Description Category	Controller Description API Format Name	Controller Description Command Suffix
  *APPC	CTLD0300	APPC
  *ASYNC	CTLD0400	ASC
  *BSC	CTLD0500	BSC
  *FNC	CTLD0600	FNC
  *HOST	CTLD0700	HOST
  *LWS	CTLD1200	LWS
  *NET	CTLD0800	NET
  *RTL	CTLD0900	RTL
  *RWS	CTLD1000	RWS
  *TAP	CTLD1300	TAP
  *VWS	CTLD1100	VWS
  A specific controller type value	Appropriate format	Appropriate suffix

  
  
  
• Device description

  If the configuration description type parameter is *DEVD (device description), the value is one of the following.

  Note: The Retrieve Device Description (QDCRDEVD) API can be used to retrieve detailed information about the configuration description. Use a format name shown in the following table as input when you call the QDCRDEVD API.

  Device Description Category	Device Description API Format Name	Device Description Command Suffix
  *APPC	DEVD0200	APPC
  *ASP	DEVD1900	ASP
  *ASYNC	DEVD0300	ASC
  *BSC	DEVD0400	BSC
  *CRP	DEVD1800	CRP
  *DKT	DEVD0500	DKT
  *DSP	DEVD0600	DSP
  *FNC	DEVD0700	FNC
  *HOST	DEVD0800	HOST
  *INTR	DEVD0900	INTR
  *MLB	DEVD1700	MLB
  *NET	DEVD1000	NET
  *NWSH	DEVD2000	NWSH
  *OPT	DEVD1600	OPT
  *OPTMLB	DEVD1700	MLB
  *PRT	DEVD1100	PRT
  *RTL	DEVD1200	RTL
  *SNPT	DEVD1300	SNPT
  *SNUF	DEVD1400	SNUF
  *TAP	DEVD1500	TAP
  *TAPMLB	DEVD1700	MLB
  A specific device type value	Appropriate format	Appropriate suffix

  
  
  
• Network interface description

  If the configuration description type parameter is *NWID (network interface description), the value is one of the following:

  Note: There is no API available to retrieve network interface descriptions. Therefore, the API format name is set to blanks and is not included in the following table.

  Network Interface Description Category	Network Interface Description Command Suffix
  *ATM	ATM
  *FR	FR
  *ISDN	ISDN
  *T1	T1

  
  
  
• Network server description

  If the configuration description type parameter is *NWSD (network server description), the value is one of the following:

  Note: The Retrieve Network Server Description (QDCRNWSD) API can be used to retrieve detailed information about the configuration description. Use a format name shown in the following table as input when you call the QDCRNWSD API. The command suffix is set to blanks.

  Network Server Description Category	Network Server Description API Format Name
  *AIX	NWSD0500
  *BASE	NWSD0400
  *GUEST	NWSD0700
  *ISCSI	NWSD0800
  *LANSERVER	NWSD0200
  *WINDOWSNT, *IXSVR	NWSD0600

  
  
  

Note: The category values are derived from the command that is used to create the configuration description.

Configuration description command suffix. The configuration description command suffix consists of the last characters (up to 4) that are associated with the create and change command for the configuration description types.

Note: For the format name values, see the tables defined for the configuration description category field.

Configuration description type specified. The value specified for the type of configuration description to be included in the list.

The possible types are:

*LIND	Line descriptions
*CTLD	Controller descriptions
*DEVD	Device descriptions
*NWID	Network interface descriptions
*NWSD	Network server descriptions
*NTBD	NetBIOS descriptions
*IPXD	Internetwork Packet Exchange (IPX) descriptions

Configuration description type used. The type of configuration description included in the list.

Current status. The current status of the selected object using two fields:

• Current status: numeric code
• Current status: displayable text

Note: The displayable text will be returned translated. This text is retrieved from message CPX2651 in message file QCPFMSG in *LIBL. If the job CCSID, message file CCSID, or message description CCSID is 65535 the displayable text is returned in the CCSID of the message description and not in the CCSID found in the generic header of the user space. The value is one of the following:

Status Numeric Code (decimal)	Status Displayable Text
0	VARIED OFF
1	OPERATIONAL
2	AS/36 DISABLED
5	DEALLOCATED
6	UNPROTECTED
7	ALLOCATED
8	STAND-ALONE
10	VARY OFF PENDING
20	VARY ON PENDING
21	VARY ON PENDING/DETACHED
22	VARY ON PENDING/ALLOCATE
30	VARIED ON
31	VARIED ON/ALLOCATE
32	VARYON/CNNPENDING
33	AS/36 ENABLED
40	CONNECT PENDING
50	SIGNON DISPLAY
51	ACTIVE/CNN PENDING
60	ACTIVE
61	ACTIVE/DETACHED
62	ACTIVE/SOURCE
63	ACTIVE READER
64	ACTIVE/TARGET
65	ACTIVE/ALLOCATE
66	ACTIVE WRITER
67	AVAILABLE
68	UNAVAILABLE
70	HELD
71	HELD/DETACHED
72	HELD/SOURCE
73	HELD/TARGET
74	HELD/ALLOCATE
75	POWERED OFF
80	RCYPND
81	RCYPND/DETACHED
82	RCYPND/SOURCE
83	RCYPND/TARGET
84	RCYPND/ALLOCATE
90	RCYCNL
91	RCYCNL/DETACHED
92	RCYCNL/SOURCE
93	RCYCNL/TARGET
94	RCYCNL/ALLOCATE
95	SYSTEM REQUEST
96	REBUILD
100	FAILED
101	FAILED/DETACHED
102	FAILED/SOURCE
103	FAILED READER
104	FAILED/TARGET
105	FAILED/ALLOCATE
106	FAILED WRITER
107	SHUTDOWN
110	DIAGNOSTIC MODE
111	*DAMAGED
112	*LOCKED
113	*UNKNOWN
114	DEGRADED
200	INVALID STATUS

Format name specified. The name specified for the format to be used in generating the list. The possible formats are:

CFGD0100	List of selected configuration descriptions
CFGD0200	List of selected configuration descriptions, plus current status of each one

Job name. The name of the job associated with an active device, if applicable.

Job number. The job number portion of a fully qualified job name.

Last activity date. The date of last activity on the object. The date format used is CYYMMDD, where:

blank	No activity date has been determined by the operating system
C	Century, where 0 indicates years 19xx and 1 indicates years 20xx
YY	Year
MM	Month
DD	Day

Object qualifier specified. The qualifier values specified that define which objects are to be included in the generated list. See the Object qualifier parameter in the Required Parameter Group for details on the possible values.

Object qualifier used. The qualifier values used to determine which objects are included in the list.

Pass-through device. The name of an upstream device used to complete a pass-through session, if applicable. This field is only filled in for SNA pass-through devices. These devices are created using the Create Device Description (SNA Pass-Through) (CRTDEVSNPT) command. If an SNA pass-through device does not exist, the field is blank.

Reserved. Space included for alignment.

Retrieve API format name. The format name that is used to retrieve detailed information about a configuration description by using a retrieve API. The following are the available APIs:

Retrieve Line Description (QDCRLIND)
Retrieve Controller Description (QDCRCTLD)
Retrieve Device Description (QDCRDEVD)
Retrieve Network Server Description (QDCRNWSD)

Note: This field is filled in only for configuration description categories of *LIND, *CTLD, *DEVD, and *NWSD. For the format name values, see the tables defined for the configuration description category field.

Status qualifier specified. The status values specified that define which configuration descriptions are to be included in the generated list. See the Status qualifier parameter in the Required Parameter Group for details on the possible values.

Status qualifier used. The status values used to determine which configuration descriptions are included in the list.

Text description. The text that describes the selected object.

User name. The user name portion of a fully qualified job name.

User space library name specified. The name specified for the library that contains the user space to receive the generated list.

User space library name used. The actual name of the library used to contain the user space that received the list.

User space name specified. The name specified for the user space that is to receive the generated list.

User space name used. The actual name of the user space that received the list.

Error Messages

Message ID	Error Message Text
CPF24B4 E	Severe error while addressing parameter list.
CPF26A8 E	Configuration description type not valid for this API.
CPF26A9 E	Object qualifier not valid for this API.
CPF26AA E	Status qualifier not valid for this API.
CPF3C21 E	Format name &1 is not valid.
CPF3C90 E	Literal value cannot be changed.
CPF3CF1 E	Error code parameter not valid.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.

---

API introduced: V2R3

---

[ Back to top | Configuration APIs | APIs by category ]