Create Low-Level Environment (QsnCrtEnv) API
Required Parameter Group:
| 1 | Low-level environment description | Input | Char(*) |
| 2 | Length of low-level environment description | Input | Binary(4) |
Omissible Parameter Group:
| 3 | User Extension Information | Input | Char(*) |
| 4 | Length of user extension information | Input | Binary(4) |
| 5 | Low-level environment handle | Output | Binary(4) |
| 6 | Error Code | I/O | Char(*) |
Returned Value:
| Low-level environment handle | Output | Binary(4) |
Default Public Authority: *USE
Service Program: QSNAPI
Threadsafe: No
The Create Low-Level Environment (QsnCrtEnv) API creates an operating environment for low-level interface routines.
Authorities and Locks
- Display file authority
- *USE
- Display file library authority
- *USE
- Exit routine authority
- *EXECUTE
Required Parameter Group
- Low-level environment description
- INPUT; CHAR(*)
The environment description for the low-level interfaces. The format of this parameter is shown in Format of the Low-Level Environment Description.
- Length of low-level environment description
- INPUT; Binary(4)
The length of the low-level environment description parameter. The value specified must be 16, 36, or 38.
Omissible Parameter Group
- User extension information
- INPUT; CHAR(*)
The user extension information is used to associate data and exit routines with the low-level environment. This essentially enables the object-oriented programming concept of inheritance, allowing the low-level environment to be extended in a natural way. The user extension information cannot be changed once the environment has been created. The format of this parameter is shown in Format of the Low-Level User Environment Extension Information.
- User extension information length
- INPUT; BINARY(4)
The length of the user extension information parameter. If this parameter is specified with a zero value, the user extension information parameter is ignored. If a non-zero value is specified, it must be 48 and the user extension parameter is required.
- Low-level environment handle
- OUTPUT; BINARY(4)
The low-level environment that is created as a result of this operation. This handle can be used across activation groups if the activation group in which the handle was created is still active.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.
Returned Value
- Low-level environment handle
- OUTPUT; BINARY(4)
The value for parameter 5 is returned. If an error occurs during processing, returns -1.
Format of the Low-Level Environment Description
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | CHAR(1) | Color support |
| 1 | 1 | CHAR(1) | Character conversion |
| 2 | 2 | CHAR(1) | CDRA conversions to 0x3F |
| 3 | 3 | CHAR(1) | DBCS support |
| 4 | 4 | CHAR(1) | Coexistence |
| 5 | 5 | CHAR(1) | Alternative help key support |
| 6 | 6 | CHAR(10) | Target device |
| 16 | 10 | CHAR(20) | Display file |
| 36 | 24 | CHAR(1) | Invite active |
| 37 | 25 | CHAR(1) | Prevent override |
Format of the Low-Level User Environment Extension Information
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | PTR(SPP) | User data associated with the environment |
| 16 | 10 | PTR(PP) | Exit routine to call when the low-level environment is changed |
| 32 | 20 | PTR(PP) | Exit routine to call when the low-level environment is deleted |
Field Descriptions
In the following descriptions, specifying the value Same indicates the current value when using the Change Low-Level Environment (QsnChgEnv) API. The default value refers to the value set by the Initialize Low-Level Environment Description (QsnInzEnvD) API.
Alternative help key support. Specifies if the alternative help key is used. The default is no alternative help key support.
The possible values for this field are:
| 0 | Same: Keep the current setting. |
| 1 | None: No alternative help key support is used. |
| QSN_F1 through QSN_F24 | The specified key is the alternative help key. See the AID Codes table for the values that correspond to these mnemonics. When this key is pressed, the AID code for the Help key will be returned. |
CDRA conversions to X'3F'. When CDRA conversion takes place, all characters not supported in the target CCSID are converted to X'3F'. Sending data containing X'3F' to the display causes adverse effects.
This field specifies whether the DSM low-level routines are to check for X'3F' in the data to be displayed and perform any conversions if necessary. Conversion will be performed for both direct and indirect operations on data output through the QsnWrtDta and QsnWrtTDta APIs, and input through the QsnReadInp, QsnReadMDT, QsnReadMDTAlt, QsnReadMDTAlt, QsnReadImm, and QsnReadMDTImmAlt APIs.
The default is convert if character conversion (see below) is specified as convert. Otherwise, the default is standard. (See Limitations and Restrictions for further details.)
The possible values for this field are:
| 0 | Same: Keep the current setting. |
| 1 | Standard: Always display data as standard data with no replacement. |
| 2 | Convert: Always check for X'3F' in data and convert to X'1F' before displaying the data and convert X'1F' in incoming data to X'3F'. |
Character conversion. This field specifies whether CDRA conversion takes place on the data when the job CCSID does not match that of the display device. Conversion will be performed for both direct and indirect operations on data output through the QsnWrtDta and QsnWrtTDta APIs, and input through the QsnReadInp, QsnReadMDT, QsnReadMDTAlt, QsnReadMDTAlt, QsnReadImm, and QsnReadMDTImmAlt APIs.
The CCSID for the display device is determined from the CHRID of the device. The default is convert if the job CCSID does not match that of the underlying device; otherwise, standard is the default.
The possible values for this field are:
| 0 | Same: Keep the current setting. |
| 1 | Standard: Do not perform conversion. |
| 2 | Convert: If the job CCSID does not match that of the display device and neither has the value 65535, perform the appropriate conversion on outgoing and incoming data. (See Limitations and Restrictions for further details.) |
Coexistence. Whether DSM coexists with other screen I/O methods, such as DDS- or UIM-coded interfaces, during the course of this application. Better performance can be achieved if coexistence is not required; the DSM APIs can assume the state of the device, for example, wide or normal mode.
The default is 1.
The possible values for this field are:
| 0 | Same: Keep the current setting. |
| 1 | Coexist: Other screen I/O methods are used in conjunction with DSM. |
| 2 | Only: DSM is the only screen I/O method being used. |
Color support. This field determines the color selection used when both a monochrome and a color display attribute are supplied. The default is select.
The possible values for this field are:
| 0 | Same: Keep the current setting. |
| 1 | Mono: Always use the monochrome attributes specified regardless of the underlying device type. |
| 2 | Always use the color attributes specified regardless of the underlying device type. |
| 3 | Select: Select the appropriate attribute based on the underlying display type. |
DBCS support. This field specifies whether the data being sent to the display contains DBCS data. This field affects, for example, how data is handled within sessions. For devices that do not support DBCS data, the default is standard; for DBCS-capable devices, it is mixed. If a value other than standard is specified for a device that does not support DBCS data, a CPFA306 error will occur.
The possible values for this field are:
| 0 | Same: Keep the current setting. |
| 1 | Standard: Always handle data as single-byte characters. |
| 2 | Only: Data contains double-byte characters only. SO/SI control characters must enclose the data; these are not implicitly added. |
| 3 | Either: Data contains either double-byte or single-byte characters, but not both. SO/SI control characters must enclose the DBCS part of the data, unless a graphic DBCS value is passed. In this case, extended ideographic attributes must enclose the data, which can be written using the QsnWrtDta API (see Write Data (QsnWrtDta) API). |
| 4 | Mixed: Data may contain both single- and double-byte characters. All double-byte character strings within the data must be enclosed by SO/SI control characters. Graphic DBCS data must be enclosed by extended ideographic attributes as described for the preceding value. |
Display file. The name of the display file to be used. The first 10 characters contain the file name, and the last 10 characters contain the library name. By specifying a display file, you can, for example, direct the input/output of different DSM environments to different devices, and you can specify the restore display parameter on the display file at creation time. The default for this field is blanks, which indicate that the system-supplied display file should be used.
If a file name is specified, the file must contain a record named USRRCD. This record must have the USRDFN keyword specified.
Exit routine to call when low-level environment changed. Exit routine to call when the low-level environment is changed through the QsnChgEnv or QsnSetEnvWinMod API. For a description of the parameters passed to this routine, see Change Low-Level Environment Exit Routine. Specify NULL for this field if no exit routine is required.
Exit routine to call when low-level environment deleted. Exit routine to call when the low-level environment is deleted through the QsnDltEnv API. The exit routine will be called before the environment itself is deleted. For a description of the parameters passed to this routine, see Delete Low-Level Environment Exit Routine. Specify NULL for this field if no exit routine is required.
Invite active. This field determines whether each write that is sent out causes the device to be invited. After the device is invited, the user is able to enter data, but the application can continue processing instead of waiting for input. When the application is ready for the input, it can call QsnReadInvited, which will issue a read from invited device operation.
The invite active flag is ignored by the read APIs, like QsnReadMDT. If the operation is indirect, then the read command will be added to the command buffer. This command buffer can be passed into the QsnReadInvited API, where it will be sent out before the read from invited device is done. If the operation is direct, then the read command will be sent in a data stream to the device. The new data stream will cause the invite to be retracted. A read with wait will be performed.
If the display file value is specified for the environment, the INVITE keyword must be specified on the USRRCD record of the specified display file.
The timeout value for the read from invited device operation can be controlled, by supplying a display file for the environment. The WAITRCD parameter on the CRTDSPF command can be set to the desired timeout value. See the return value for the QsnReadInvited API to determine the return value if the read from invited device operation times out.
The possible values for this field are:
| 0 | Same: Keep the current setting. |
| 1 | Not active: The INVITE keyword, if specified in the display file, will be ignored. A normal read of the device will be performed. |
| 2 | Active: Any request to get data from the display will result
in a read from invited device being issued.
For more information about invite processing, see the Application Display
Programming |
manual.Prevent override. This field determines whether the display file used by DSM can be overridden or not. This value is ignored if the display file value is not specified.
The possible values for this field are:
| 0 | Same: Keep the current setting. |
| 1 | Do not prevent override: When opened, the display file will allow overrides. For create and initialize operations, this is the default. |
| 2 | Prevent overrides: When the display file is opened, the flag to block overrides will be set. |
User data associated with the environment. A pointer to any data the user wants to associate with this environment. This field can be used by the programmer to attach information to the low-level environment that can be of any format. For example, if multiple environments are being used, a list of the fields currently defined in an environment could be associated with the environment through this pointer. Specify NULL for this field if you do not have any user data.
Target device. The program device name of the target display device for the environment. This parameter must be specified with a value of *REQUESTER, which is the default.
Exit Routine Error Handling
If an exception occurs during the processing of an exit routine, the exception is ignored and processing continues. A CPFA318 will be issued as a diagnostic message only. You can explicitly handle errors in an exit routine by adding an exception handler to the routine.
Change Low-Level Environment Exit Routine
This exit routine, if specified on the user extension information, is called after the environment is changed through the QsnChgEnv or QsnSetEnvWinMod API. The following parameter is passed to the exit routine:
| 1 | Low-level environment handle | Input | Binary(4) |
Change Low-Level Environment Exit Routine Parameter
- Low-level environment handle
- INPUT; BINARY(4)
A handle for the environment that was changed.
Delete Low-Level Environment Exit Routine
This exit routine, if specified on the user extension information, is called before the environment is deleted. The following parameter is passed to the exit routine:
| 1 | Low-level environment handle | Input | Binary(4) |
Delete Low-Level Environment Exit Routine Parameter
- Low-level environment handle
- INPUT; BINARY(4)
A handle for the environment that was deleted.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C1D E | Length specified in parameter &1 not valid. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPFA314 E | Memory allocation error. |
| CPFA31E E | Required parameter &1 omitted. |
| CPFA327 E | Low level environment description value incorrect. |
| CPFA344 E | The file &2 in library &3 is not valid. |
API introduced: V2R3
[ Back to top | Dynamic Screen Manager APIs | APIs by category ]