Set Field (QsnSetFld) API
Omissible Parameter Group:
| 1 | Field ID | Input | Binary(4) |
| 2 | Field length | Input | Binary(4) |
| 3 | Row | Input | Binary(4) |
| 4 | Column | Input | Binary(4) |
| 5 | Field format word (FFW) | Input | Char(2) |
| 6 | Field control words (FCW) | Input | Char(*) |
| 7 | Number of field control words | Input | Binary(4) |
| 8 | Monochrome attribute | Input | Char(1) |
| 9 | Color attribute | Input | Char(1) |
| 10 | Command buffer handle | Input | Binary(4) |
| 11 | Low-level environment handle | Input | Binary(4) |
| 12 | Error code | I/O | Char(*) |
Returned Value:
| Return code | Output | Binary(4) |
Default Public Authority: *USE
Service Program: QSNAPI
Threadsafe: No
The Set Field (QsnSetFld) API defines an 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:
- Any outstanding AID requests are cleared.
- The keyboard is locked.
- If there is an entry in the format table whose starting address is equal to
the address for this field, then that entry is modified. The FFW of the
existing entry is replaced by the new FFW and the previous screen starting
attribute is overlaid with the new screen starting attribute. The ending screen
attribute is not rewritten. All FCWs and the length parameter are ignored. See
the 5250 data stream documentation for details.
- If no entry can be found in the table for the field being defined, a new entry will be added to the end of the table. However, the address must be greater than the ending address of the field currently defined last in the format table or an error will occur. If the new entry is valid, it will contain the field's FFW, the optional FCWs, and the field's starting and ending address. An error will occur if an attempt is made to define too many fields on the screen (see the 5250 data stream documentation for details).
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. (For an indirect operation, a WTD is placed in the command buffer only if one does not already exist in that buffer.)
Authorities and Locks
None
Restrictions
The same restrictions apply as for the Write Data (QsnWrtDta) 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.)
Omissible Parameter Group
- Field ID
- INPUT; BINARY(4)
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.
- Field length
- INPUT; BINARY(4)
The length of the field being defined. 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.
- Row
- INPUT; BINARY(4)
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 field length.
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.
- Column
- INPUT; BINARY(4)
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 center 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.
- Field format word (FFW)
- INPUT; CHAR(2)
The field format word is a 2-byte value that controls the type of the field being defined. 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.
- Field control words (FCW)
- INPUT; CHAR(*)
An array of 2-byte field control words. The field control words are 2-byte values that request certain functions to be performed. Table 7 shows the valid field control word values, their function, and mnemonics for those values.
The 5250 CCSID-based I/O specific FCWs are not allowed (QsnSetFldCC must be used to create CCSID-capable fields). 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 8 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.
- Number of field control words
- INPUT; BINARY(4)
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.
- Monochrome attribute
- INPUT; CHAR(1)
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.
- Color attribute
- INPUT; CHAR(1)
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.
- Command buffer handle
- INPUT; BINARY(4)
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.
- Low-level environment handle
- INPUT; BINARY(4)
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.
- 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
- Return code
- OUTPUT; BINARY(4)
A return code indicating the result of the operation. The value returned will be 0 if the operation was successful, or -1 otherwise.
Format of the Field Format Word
The following table shows the field types and the bits to set for each type for the field format word (FFW).
Table 6. Field Format Words
| Field Type | Bit To Set | Mnemonic | Description |
|---|---|---|---|
| 0-15 | QSN_NO_FFW | If bits 0 to 15 are set to 0, then no FFW is used. The field will be defined as an output field and its contents will not be returned by operations such as the Read Input Fields (QsnReadInp) API. | |
| 0-1 | The first two bits of a field format word must be 01. The mnemonic for every other field type includes this setting. | ||
| Bypass | 2 | QSN_FFW_BYPASS | If this bit is set, this is a bypass field and entries are not allowed in it. If the operator tries to enter something in this field, an error results. |
| Dup Enable | 3 | QSN_FFW_DUP | If this bit is set, duplication is allowed in the field. The controller repeats X'1C' from the cursor position to the end of the field when the operator presses the Dup key; this shows on the display as an overstruck asterisk. |
| Modified data tag (MDT) | 4 | QSN_FFW_MDT | Setting this bit sets the modified data tag for this field. The field will then be read with the Read Modified Fields (QsnReadMDT) API (see Read Modified Fields (QsnReadMDT) API) as if the operator had modified it. |
| Field Shift/ Edit Specification | Bits 5-7 | Mnemonic | Description |
| Alphabetic shift | 000 | QSN_FFW_ALPHA_SHIFT | The field accepts all characters. The shift keys are acknowledged. The characters on the lower symbol of each key are valid. |
| Alphabetic only | 001 | QSN_FFW_ALPHA_ONLY | The field accepts only characters A-Z (both uppercase and lowercase) plus the comma (,), period (.), minus (-), space, and DUP (if the DUP-enable bit is on in the associated Field Format Word (FFW)). Other characters cause operator errors. Some special characters are also acceptable (see the 5250 data stream documentation). |
| Numeric shift | 010 | QSN_FFW_NUM_SHIFT | The field accepts all characters from all keys. |
| Numeric only | 011 | QSN_FFW_NUM_ONLY | The field accepts only characters 0-9 and the
comma (,), period (.), minus (-), plus (+), space, and DUP (if the DUP-enable
bit is on in the associated Field Format Word (FFW)). Other characters cause
operator errors.
The unit position of this field will carry the sign digit for the field. If the field is exited with the Field - key, the last character in the field will be 'D' zoned, unless the last character in the field is a '+', '-', ',', '.', or space, in which case an error will be posted. In a center-adjusted field, the field will be center-adjusted before any 'D' zoning or testing of the sign character is performed. When a negative field (from the Field - key) is returned, the units digit will have a 'D' zone. |
| Katakana shift | 100 | QSN_FFW_KATA | This is the same as the alphabetic shift except that the keyboard is placed in the Katakana shift on the Japan Katakana data entry, typewriter, and G keyboards. This reverses the order of the cursor direction with respect to the screen. If the display is in bidirectional mode, this changes the cursor direction to left to center; otherwise, it changes the cursor direction to center to left. |
| Digits only | 101 | QSN_FFW_DIGIT_ONLY | The field allows keys 0-9 and DUP (if the DUP-enable bit is on in the associated Field Format Word (FFW)). |
| I/O | 110 | QSN_FFW_IO | This field will not accept any data keys from the
keyboard. An operator error is posted if keystrokes are entered in this field.
The operator may move the cursor into and out of this field similar to
operation in any non-bypass input field (that is, Field Advance will position
the cursor to the start of the field).
This field can be used for input from feature devices such as a magnetic stripe reader of selector light pen while data input from the keyboard is excluded. The Field +, Field Exit, and Dup keys are valid for this field and performance is the same as that for any non-bypass input field. |
| Signed Numeric | 111 | QSN_FFW_SIGNED_NUMERIC | The field allows keys 0-9 and DUP (if the
DUP-enable bit is on in the associated Field Format Word (FFW)). Typing any
other character will cause an operator error display.
This field reserves the center-hand position for a sign display (- for negative and null for positive); therefore, the largest number of characters that can be entered into this field is one less than the field length. A signed numeric field less than 2 characters long will cause an error to be flagged. No digit may be keyed into the centermost position; however, the cursor can be positioned there by using the cursor movement keys and then followed by the F+ or F- key. This allows changing the sign without affecting the rest of the field. |
| Signed Numeric (continued) | If this field is not a mandatory fill or
center-adjust field, it is still handled as if it were specified as a
center-adjust blank fill field. If the Field - key is used to exit this field,
the field will be center-adjusted and a negative sign placed in the centermost
position of the field. The Field Exit or Field + key will insert a blank in the
centermost position and center-adjust this field.
Before this field is returned on an input operation, it is changed as follows:
In either case, the centermost sign position is not sent to the host. |
||
| Field Type | Bit to Set | Mnemonic | Description |
| Auto Enter | 8 | QSN_FFW_AUTO_ENTER | If this bit is set, this is an auto enter field. The auto enter function occurs only for valid Field Exit/Field +, Field -, and Dup exit keys, or if the last data character position is typed into the auto enter field. After any required center-adjust, mandatory fill, data duplicating, or check digit operations are successfully performed, the auto enter function causes the panel to be sent to the host as if the Enter key had been pressed. |
| Field Exit Required | 9 | QSN_FFW_AUTO_FER | If this bit is set, a nondata key must be typed to leave the field. When the last data character is typed into the last position of the field, the cursor will remain under the character and blink, signifying the controller is waiting for an exit key. Any nondata key will satisfy the exit requirement (including cursor movement or function keys). |
| Monocase | 10 | QSN_FFW_AUTO_MONOCASE | If this bit is set, then regardless of the shift state of the typewriter keyboard, only the uppercase A-Z is entered into the field being typed (that is, if a lowercase a is typed, the uppercase A is entered). All other characters are unaffected. Certain characters on some typewriter keyboards also will be translated to uppercase (see the 5250 data stream documentation). |
| Reserved | 11 | ||
| Mandatory Enter | 12 | QSN_FFW_ME | If this bit is set, the operator must enter something in the field before the controller allows the Enter key to be active. The controller recognizes the state of these fields by checking the MDT bit for the field. If the operator tries to bypass the field using a Field +, Field -, or Field Exit key, an error occurs. |
| Center-Adjust/ Mandatory Fill | Bits 13-15 | Mnemonic | Description |
| No adjust specified | 000 | QSN_FFW_NOADJUST | No field adjustment occurs. |
| Reserved | 001 | ||
| Reserved | 010 | ||
| Reserved | 011 | ||
| Reserved | 100 | ||
| Center-adjust, zero fill | 101 | QSN_FFW_RA_ZERO | All leftmost unoccupied positions of a field are
filled with zero. Characters are center-adjusted and spaces are zero-filled.
The fill character will appear on the display.
center-adjust is only activated by keying the Field Exit, Field +, or Field - keys. The field is center-adjusted from the first non-null character to the left of the cursor when one of these keys is depressed. If a center-adjust field is left through cursor movement keys, the field will remain as is (not center-adjusted). center-adjust fields longer than 15 characters might cause a slow response that would result in a keyboard overrun. A center-adjust specified field has an implied field exit required function. The Dup key will fill a center-adjust field from the cursor to the end of the field with the Dup character (X'1C'), but the field will not be center-adjusted. After typing the first character into a center adjust field, but prior to exiting the field (using cursor movement or exit keys), the Enter key will cause an operator error to be posted; that is, Enter is invalid from an active center-adjust field. |
| Center-adjust, blank fill | 110 | QSN_FFW_RA_BLANK | The field behavior is the same as for center-adjust, zero fill, but the fill character is blank instead of zero. |
| Mandatory fill | 111 | QSN_FFW_MF | Once any data has been entered into the field,
the field must be completely filled before exiting it. Any attempt to leave an
unfilled field causes an error. The cursor may pass into and out of a mandatory
fill field as a result of cursor movement keys without fill-checking or error
posting by the controller, as long as no data is entered into the field.
The Dup key will fill the field from the cursor to the end of field with the Dup characters X'2C', and then the entire field will be checked for any nulls (an error is posted if a null is found). A mandatory fill field with nulls can be returned under the following conditions:
The above fields, with no further entry, can be returned with all data as blanks on a Read Input Fields (QsnReadInp) operation or as a null field on a Read Modified Fields (QsnReadMDT) operation. |
Format of the Field Control Word
The following table explains the valid field control words (FCW) for use with the QsnSetFld API.
Table 7. 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'8200' | QSN_FCW_DBCS_ONLY | DBCS only entry field. |
| X'8220' | QSN_FCW_DBCS_PURE | DBCS Graphic DBCS entry field. |
| X'8240' | QSN_FCW_DBCS_EITHER | DBCS Either entry field. |
| X'8280', X'8281', or X'82C0' | QSN_FCW_DBCS_OPEN, QSN_FCW_DBCS_OPEN_ALL, or QSN_FCW_DBCS_OPEN_C0 | DBCS open entry field. |
| X'84??' | QSN_FCW_TRANSPARENT | Transparency entry field (used in the Read Input Fields (QsnReadInp) and Read Modified Fields (QsnReadMDT) APIs, and so forth). The ?? indicates that these values are ignored. |
| 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. |
Valid Field Control Word and Device Capability Combinations
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 QsnSetFld and the corresponding device capability is not supported, a CPFA306 will result. QsnSetFld, 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.
Table 8. 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 |
| QSN_FCW_DBCS_ONLY, QSN_FCW_DBCS_EITHER, QSN_FCW_DBCS_OPEN, QSN_FCW_DBCS_OPEN_ALL, QSN_FCW_DBCS_OPEN_C0 |
DBCS |
| QSN_FCW_DBCS_PURE | Pure DBCS |
| QSN_FCW_TRANSPARENT | Transparent Data |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| 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. |
API introduced: V2R3
[ Back to top | Dynamic Screen Manager APIs | APIs by category ]