| 1 | Field ID | Input | Binary(4) |
| 2 | Field length | Input | Binary(4) |
| 3 | Display Positions | Input | Binary(4) |
| 4 | CCSID | Input | Binary(4) |
| 5 | Row | Input | Binary(4) |
| 6 | Column | Input | Binary(4) |
| 7 | Field format word (FFW) | Input | Char(2) |
| 8 | Field control words (FCW) | Input | Char(*) |
| 9 | Number of field control words | Input | Binary(4) |
| 10 | Monochrome attribute | Input | Char(1) |
| 11 | Color attribute | Input | Char(1) |
| 12 | Command buffer handle | Input | Binary(4) |
| 13 | Low-level environment handle | Input | Binary(4) |
| 14 | Error code | I/O | Char(*) |
| Return code | Output | Binary(4) |
The Set Field with CCSID (QsnSetFldCC) API defines a CCSID-capable input field on the screen at the given row and column. The following occurs when this command is issued to the control unit as a direct operation or when the buffer containing the command is written out:
The display address after this operation will be the starting field address minus 1 if row and column are specified as valid positive integers or if this is the first field specified within the current WTD command. Otherwise, the display address will be one position past the ending screen attribute.
This command corresponds indirectly to the 5250 Write to Display (WTD) command with a Set Buffer Address order and a Start of Field order if the row and column parameters are specified. Special FCWs inserted into the data stream by this API to make the field CCSID-capable. (For an indirect operation, a WTD is placed in the command buffer only if one does not already exist in that buffer.)
The same restrictions apply as for the Write Data with CCSID (QsnWrtDtaCC) API, with the exception that the trailing field attribute can be written past the end of the screen. (It will be suppressed by the control unit.)
This command is not supported by all control units. A CPFA306 error occurs if an attempt is made to issue this command to a control unit that does not support it.
The CCSID value given must be supported by the device or emulator, otherwise a CPF3BDE will be signaled.
None
The field ID to be associated with this field. The value specified can be any nonzero integer value. For APIs that accept a field ID parameter, this value can be subsequently used instead of the row and column parameter to specify a screen address. If the given ID is already defined, this operation will redefine that field ID with the values specified. To remove a field ID definition, use the QsnDltFldId API.
If a previously defined field ID is supplied and some or all of the parameters are omitted, the field is defined using the current field definition values for those omitted parameters.
If this field is omitted or specified with a value of zero, then no field ID is associated with this field description.
The number of bytes that this field being defined contains (a single character might be composed of multiple bytes). If no field ID is specified, the length must be a positive integer value greater than 1 for signed numeric fields and greater than 0 for all other field types. The entire field must fit on the display. If a field ID is specified with a nonzero value, the length may be 0, in which case a field will not be defined on the screen; however, this will associate the field definition with the specified field ID.
The number of positions on the display allowed for this field being defined (a single character may require more than one position on the display).
If this parameter is not specified, the default is the number given by the field length parameter.
The CCSID of the data that can be entered into this field. If the CCSID given is not supported by the device, a CPF3BDE is signaled.
If this parameter is omitted (zero is passed in as the CCSID), and the field ID parameter was omitted or previously undefined, the job CCSID is used. If the job CCSID is 65535, the default job CCSID is used instead.
The row at which to define the field. The row parameter must refer to a row no greater than the current screen or window mode height (if window mode is enabled). The actual screen row used for a screen I/O operation is calculated using the formula base+offset=actual. The base is the row location of the top window border (0 for full screen) if offset is positive, or the row location of the bottom window border (screen height plus 1 for full screen) if offset is negative. The offset is the row parameter value specified, and actual is the actual screen row to be used. A CPFA307 error occurs if an incorrect row value is specified.
The starting field address will be the row and column locations given if both parameters are specified. Otherwise, it will be the current display address plus 1. If this is the case and the command is a direct operation, or the buffer specified does not contain a preceding output operation that sets the display address, the current display address is set to row 1, column 1, prior to writing the initial screen attribute and the field definition. The ending field address for this field is the starting field address plus the number of character positions for the field.
If a field ID is supplied along with a row and column, the row and column parameters will be stored as specified. These parameters will be used as relative or actual screen positions on a subsequent operation, depending upon the window mode setting for the environment supplied with that operation.
If a previously undefined field ID is supplied with this operation, the row and column parameters must be specified. Also, the row and column parameters must both be specified or omitted; one cannot be specified if the other is omitted. A CPFA307 error occurs if an incorrect cursor position is specified. On some devices, row and column can both be specified as 1, which will cause the field to be defined at row 1, column 1, with a screen attribute of normal (X'20'). If this is the case, then any initial screen attribute parameters specified are ignored. This is only supported by certain devices. Whether or not this is supported can be determined by the Query 5250 (QsnQry5250) API.
The column at which to write the data. The column parameter must refer to a column no greater than the current screen or window mode width (if window mode is on). The actual screen column used for a screen I/O operation is calculated using the formula base+offset=actual. The base is the column location of the left window border (0 for full screen) if offset is positive, or the column location of the right window border (screen width plus 1 for full screen) if offset is negative. The offset is the column parameter value specified, and actual is the actual screen column to be used. A CPFA307 error occurs if an incorrect column value is specified.
The field format word is a 2-byte value that controls the type of the field being defined. QsnSetFld Table 6 shows the field types, and the corresponding bit to be set for each type. To omit this parameter, specify X'00' in both characters of the parameter. You must specify this parameter to define an input field, and it is required if a field control word is specified.
An array of 2-byte field control words. The field control words are 2-byte values that request certain functions to be performed. Table 10 shows the valid field control word values, their function, and mnemonics for those values.
Note: The 5250 CCSID-based I/O specific FCWs are not allowed, because they are implicitly added as part of the QsnSetFldCC operation. If the CCSID-based I/O CCSID or Maximum data length FCWs are given here, a CPFA332 will result. FCWs will not be exhaustivly checked to see if they are formatted correctly or to see if the function requested is valid for the current device. However, some FCWs are checked against the support provided by the device and a CPFA306 signaled if an incompatibility is found. Table 11 shows the display capablility and FCW combinations that are valid.
Errors not found here may be detected and reported when the FCW is required during subsequent command and keystroke processing. See the 5250 data stream documentation for further details about the meaning and use of these functions.
The number of control words in the field control word array. Omitting this parameter or specifying it with a value of 0 indicates that no field control words are specified with the FCW parameter. If this parameter is specified with a nonzero value, the FCW parameter is required; if the FCW parameter is omitted, a CPFA31E error is issued.
The initial screen attribute for monochrome displays. A screen attribute is required for defining a field on the screen; if this parameter is omitted and monochrome attributes are to be used, X'20' is assumed. The initial screen attribute is written one position to the left of the starting field address. The ending screen attribute (X'20') is supplied by the controller and written at the end-of-field address plus 1.
The monochrome attribute and color attribute parameters consist of 1 byte that will be used as the screen attribute for a monochrome or a color display, respectively. One of these parameters will be selected based on the underlying display type, and the other will be discarded. See Screen Attribute Characters for a description of the screen attribute values.
The initial screen attribute for color displays. A screen attribute is required for defining a field on the screen; if this parameter is omitted and color attributes are to be used, X'20' is assumed. See Screen Attribute Characters for a description of the screen attribute values.
A handle for the command buffer in which to store the command. If this parameter is omitted or specified as 0, this is a direct operation and the starting field address will be the supplied location. Otherwise, this is an indirect operation and the command is stored in the command buffer without an I/O operation taking place.
The low-level environment that the operation applies to. If this parameter is omitted or given with a value of zero, the default low-level environment is used.
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.
A return code indicating the result of the operation. The value returned will be 0 if the operation was successful, or -1 otherwise.
The following table explains the valid field control words (FCW) for use with the QsnSetFldCC API.
| Field Control Words | ||
|---|---|---|
| FCW Value | Mnemonic | Description |
| X'80nn' | QSN_FCW_RESEQ | Entry field resequencing (used in the Read Input Fields (QsnReadInp) and Read Modified Fields (QsnReadMDT) APIs, and so forth). The nn specifies the next entry field in the sequence (nn can be X'00' to X'80'). See Resequencing. |
| X'8101' | QSN_FCW_MSR | Magnetic stripe reader entry field. |
| X'8102' | QSN_FCW_SLP | Selector light pen entry field. |
| X'8103' | QSN_FCW_MSR_SLP | Magnetic stripe reader and selector light pen entry field. |
| X'8106' | QSN_FCW_SLP_SA | Selector light pen and selectable attention entry field. |
| X'8501' | QSN_FCW_FET | Forward edge trigger entry field. This provides the same function as Auto Enter specified in the FFW, except a unique AID is returned to the host when the field is exited. The state on the Auto Enter flag in the FFW is ignored. |
| X'8601' | QSN_FCW_CONT_FIRST | Continued entry field first segment. |
| X'8602' | QSN_FCW_CONT_LAST | Continued entry field last segment. |
| X'8603' | QSN_FCW_CONT_MIDDLE | Continued entry field middle segment. |
| X'88nn' | QSN_FCW_CP | Cursor progression entry field. |
| X'89nn' | QSN_FCW_HL | Highlighted entry field. |
| X'8Ann' | QSN_FCW_PDS | Pointer device selection entry field. |
| X'B140' | QSN_FCW_MOD11 | Self Check Modulus 11 entry field. |
| X'B1A0' | QSN_FCW_MOD10 | Self Check Modulus 10 entry field. |
The following table explains the field control words (FCW) available for certain capabilities of the device. If one of the FCW values listed is given to QsnSetFldCC and the corresponding device capability is not supported, a CPFA306 will result. QsnSetFldCC, however, does not detect all invalid FCW combinations. See the Field control words (FCW) parameter for more information.
See the QsnQry5250 API to determine the capablilities supported by the current device.
| Valid Field Control Word and Device Capability Combinations | |
|---|---|
| FCW Values | Display capablility required for FCW to be valid |
| QSN_FCW_CONT_FIRST, QSN_FCW_CONT_MIDDLE, QSN_FCW_CONT_LAST, QSN_FCW_CP, QSN_FCW_HL, QSN_FCW_PDS |
ENPTUI |
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3BDE E | CCSID &1 not supported by API. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3CF2 E | Error(s) occurred during running of &1 API. |
| CPFA301 E | Command buffer is full. |
| CPFA304 E | Data-stream error &1 reported for screen I/O operation. |
| CPFA305 E | Cannot add operation to command buffer. |
| CPFA306 E | Command not supported by current device. |
| CPFA307 E | Screen position &1, &2 outside of display or window area. |
| CPFA308 E | Attempt to write data past end of display. |
| CPFA30A E | Field length &1 not valid. |
| CPFA30B E | Invalid starting address for field. |
| CPFA30C E | Maximum allowable number of fields exceeded. |
| CPFA30D E | Invalid screen attribute. |
| CPFA30E E | Invalid field format word. |
| CPFA314 E | Memory allocation error. |
| CPFA31D E | Attempt to write outside of window area. |
| CPFA31E E | Required parameter &1 omitted. |
| CPFA331 E | Buffer handle incorrect. |
| CPFA332 E | Incorrect field control word. |
| CPFA333 E | Parameter &1 not positive integer value. |
| CPFA334 E | Low level environment handle incorrect. |
| CPFA335 E | Screen address parameter error. |
| CPFA33D E | Invalid screen attribute. |
| CPFA343 E | Output operation not done. |
| CPFA344 E | The file &2 in library &3 is not valid. |
| CPFA345 E | The invite active flag is not valid. |
| Top | Dynamic Screen Manager APIs | APIs by category |