VSCREEN WRITE

Read syntax diagramSkip visual syntax diagram VSCreen WRIte vname line col length 1(2REServedOption A B)3
Option A
Read syntax diagramSkip visual syntax diagramNULlsBLAnksPRotectNOPRotectHighNOHighInvisibleMIXedSBCSBlueRedPinkGreenTurquoiseYellowWhiteDefaultNoneREVvideoBLInkUnderlinePS0PS1PS8PSAPSBPSCPSDPSEPSFBOXDefBOXBOXLeftBOXOverBOXRightBOXUnder
Option B
Read syntax diagramSkip visual syntax diagramFIELDDATACOLOREXTHIPSS text
Notes:
  • 1 The defaults you receive appear above the line in the Options fragments.
  • 2 You can enter Options in any order between the parentheses.
  • 3 If Option B is used, a right parenthesis should not be used to mark the end of the options.

Authorization

General User

Purpose

Use the VSCREEN WRITE command to define fields and modify existing fields in a virtual screen. The information is queued to the virtual screen and is displayed the next time the screen is refreshed.

Operands

vname
specifies the name of the virtual screen.
line
specifies the line number of the virtual screen where the write is to begin.
col
specifies the column number of the virtual screen where the write is to begin.
length
specifies the length to be written.
REServed
specifies the line number refers to a reserved line. If you specify RESERVED, line must be a number less than or equal to the size of the reserved area. A negative line number indicates a write in the bottom reserved area, and a positive line number indicates a write in the top reserved area.

Options

Option A

Option A specifies the padding used for data, field attributes, and extended field attributes. When modifying a previously defined field, any field attribute specified is ignored, while any extended field attribute specified is modified. These may be specified:

BLAnks
pads data with blanks.
NULls
pads data with nulls. This is the default.
PRotect
specifies a protected field.
NOPRotect
specifies a field that is not protected.
High
specifies a high-intensity field.
NOHigh
specifies a normal-intensity field.
Invisible
specifies an invisible field. The data written is not displayed on the screen.
MIXed
defines a mixed DBCS (with SO/SI positions) field when the device is a PS/55-family display.
SBCS
defines a field in which SO and SI codes may not be entered from the keyboard. However, like a MIXED field, data written to this field may contain SO and SI codes.
color
is the color of the field.
exthi
is the extended highlighting of the field.
psset
is the programmed symbol set of the field. It may be PS0, PS1, PS8, PSA, PSB, PSC, PSD, PSE, or PSF. For a loadable psset, the psset must already be loaded in the display. If no psset is loaded, PS0 is used. PS8 specifies a pure DBCS field. SET CHARMODE must be ON to display characters using PS1.
outline
is the field outlining for a PS/55-family display. Outlining may be BOXDef (the default outlining for the device), BOX (a full box), or any combination of the following to obtain the remaining 14 possible valid values:
BOXLeft
A vertical line on the left of the field.
BOXOver
Overline.
BOXRight
A vertical line on the right of the field.
BOXUnder
Underline.

For more information, see VSCREEN DEFINE.

Option B

Option B specifies the operation to perform. The following may be specified:

FIELD
defines a field, as follows:
  • The field will start at the specified line and column (a start field character is placed at this location), and have the length you specify.
  • The character attributes of all characters in the field are set to the value which defaults to the extended field attributes.
  • When FIELD is specified:
    1. Some of the options in Option A specify the field attribute of the new field. Any of these values not specified will default to the values for the vscreen.
    2. Other options in Option A specify the extended field attributes (color, extended highlighting, programmed symbol set, and field outlining.) Any of these values not specified will default to the values for the vscreen.
    3. Specify the data for the field in option B. The data will begin at the byte immediately following the start field character, and will be padded (as specified in option A) or truncated to the end of the field. The field can only hold one less character than the length you specify, due to the existence of the start field character.
DATA
modifies the data in a previously defined field. The character attributes may also be modified.
  • The modified portion of the field starts at the specified line and column and continues for the length you specify. If that length is greater than the size of the field, it will be truncated to the end of the field.
  • When DATA is specified:
    1. You will also specify the new data for the modified portion of the field with option B. It will be padded (as specified in option A) or truncated to the end of the modified part of the field.
    2. Some of the options in Option A will specify the new character attributes (color, extended highlighting, programmed symbol set, and field outlining) of all characters in the modified part of the field. Any of these values not specified will not be changed.
    3. The field attribute is not changed.
    4. The extended field attributes are not changed.
COLOR
modifies the color character attributes in a previously defined field. The data and the other character attributes (extended highlighting and programmed symbol set) may also be modified.
  • The modified portion of the field starts at the specified line and column and continues for the length you specify. If that length is greater than the size of the field, it will be truncated to the end of the field.
  • When COLOR is specified:
    1. Option B will specify the new color character attribute for each character in the modified part of the field. Use the following characters to represent the colors:
      1
      Blue
      2
      Red
      3
      Pink
      4
      Green
      5
      Turquoise
      6
      Yellow
      7
      White
      0
      Defaults to the color of the field

    The text will be padded or truncated to the end of the modified part of the field. If padding occurs, it will be with the color value specified in option A, if one is given; otherwise, padding will be with the vscreen color.

  • Extended highlighting or programmed symbol set values in option A specify the new character attributes of all characters in the modified portion of the field. Any option A values not specified will not be changed.
  • Option A specifies the new data for the modified portion of the field. If option A is not specified, the data will not be modified.
  • The field attribute is not changed.
  • The extended field attributes are not changed.
EXTHI
modifies the extended highlighting attributes in a previously defined field. The data and the other character attributes (color and programmed symbol set) may also be modified.
  • The modified portion of the field starts at the specified line and column and continues for the length you specify. If that length is greater than the size of the field, it will be truncated to the end of the field.
  • When EXTHI is specified:
    1. Option B will specify the new extended highlighting attribute for each character in the modified part of the field. The following characters represent the extended highlighting:
      0
      Defaults to the extended highlight of the field
      1
      Blink
      2
      Revvideo
      4
      Underline

      The text will be padded or truncated to the end of the modified part of the field. If padding occurs, it will be with the extended highlighting value specified in option A, if one is given; otherwise, padding will be with the vscreen extended highlighting.

    2. Color or programmed symbol set values in option A specify the new character attributes of all characters in the modified portion of the field. Any option A values not specified will not be changed.
    3. Option A specifies the new data for the modified portion of the field. If option A is not specified, the data will not be modified.
    4. The field attribute is not changed.
    5. The extended field attributes are not changed.
PSS
modifies the programmed symbol set attribute in a previously defined field. The data and the other character attributes (color and extended highlighting) may also be modified.
  • The modified portion of the field starts at the specified line and column and continues for the length you specify. If that length is greater than the size of the field, it will be truncated to the end of the field.
  • When PSS is specified:
    1. Option B will specify the new programmed symbol set attribute for each character in the modified part of the field. The following characters represent the PSS: 0 and blank (default to the PSS of the field if the PSS is a loadable PSS, default to PS0, which is the terminal default, if the PSS is non-loadable), 1, A, B, C, D, E, F,
      Note: The letters must be specified in upper case.

      The text will be padded or truncated to the end of the modified part of the field. If padding occurs, it will be with the programmed symbol set value specified in option A if one is given; otherwise, padding will be with the vscreen programmed symbol set value.

    2. Color or extended highlighting values in option A specify the new character attributes of all characters in the modified portion of the field. Any option A values not specified will not be changed.
    3. Option A specifies the new data for the modified portion of the field. If option A is not specified, the data will not be modified.
    4. The field attribute is not changed.
    5. The extended field attributes are not changed.
text
is the data to be written in the field. Mixed DBCS data can be used for text when text is preceded by the FIELD or DATA keyword, and provided your terminal is capable of supporting mixed DBCS.

Usage Notes

  1. When VSCREEN WRITE is issued, the text and its characteristics are held in the virtual screen queue created by VSCREEN DEFINE. To move the text from the queue to the virtual screen, you should issue either VSCREEN WAITREAD, VSCREEN WAITT, or the PSCREEN REFRESH command. This process is required when issuing the VSCREEN WRITE command from an EXEC.
  2. Use the INVISIBLE option to prevent data from being displayed on the screen. The INVISIBLE option causes the text of the field to be ignored. A field of blanks or nulls will be defined for the length specified. You should use the LINERD macro with the INVISIBLE option for sensitive data, such as passwords.
  3. When a field is defined, the first character contains the start field. The start field is a one-byte character identifying the attributes for the field. The start field character is protected and cannot be written to. If option B is not specified, the default is FIELD.

    For more information on fields, see 3270 Data Stream Programmer's Reference.

  4. The column operand must be greater than or equal to zero. Specifying a column number of zero is valid only when writing to the scrollable area, in which case it is equivalent to specifying column number one. When writing a field, a start field is placed in the column specified. The text always begins in the next column. When writing COLOR, EXTHI, PSS, or DATA, no start field is inserted, and the text begins in the column specified, (or in the next available column if that location is a start field).
  5. Working with DBCS

    For color and extended highlighting in a DBCS string, the first byte of a double-byte character determines the attributes for both bytes. You cannot specify character attributes for PSS within a DBCS string.

  6. PS8 defines a pure DBCS field in a vscreen, when the device is a PS/55-family display with PS8 capability. You can define a pure DBCS field only when you define a field (VSCREEN WRITE with FIELD option). Once you specify PS8, you cannot change to another psset value without redefining the field. If you specify both PS8 and MIXED or SBCS, PS8 takes precedence and MIXED or SBCS is ignored.
  7. Writing Pure DBCS Data

    After a pure DBCS field is defined, you can use the DATA option to change the DBCS string in the vscreen data buffer. You can only use the DATA option to write pure DBCS text into a field already defined as pure DBCS. If you have specified PSS for the text in option B, PS8 is ignored if specified in option A.

    If you are writing to a pure DBCS field that wraps lines such that the PS8 data in the line ends up being an odd number of bytes in length, blanks will be inserted at the beginning or end of the line.

  8. All DBCS characters in the text written with VSCREEN WRITE with the FIELD or DATA option are checked for validity. The characters that are not valid are replaced by the NONDISP character defined for CMS, or by characters that indicate there is no recognizable representation for the alphanumeric characters being written.
  9. Alignment of Pure DBCS Data

    Data written in a predefined pure DBCS field must begin at a column that is the first byte of a DBCS character. If it does not do so, the text will be aligned this way, and no message or nonzero return code will be issued.

    For example, suppose you have a field at line 8 of your MESSAGE vscreen that contains a DBCS string, where @ represents the start field, K represents the first byte and 1-9 the second byte of a valid DBCS character in hexadecimal, as follows:
    @K1K2K3K4
    You want to write one DBCS character of text, K9, at column 5 (the 2 of K2) of this field. If your program issues:
    VSCREEN WRITE MESSAGE 8 5 2 (PS8 DATA K9
    You will get the following string as a result:
    @K1K9K3K4
    K9 is automatically aligned so it starts at the fourth column rather than the fifth, because starting it at the fifth column would have resulted in a not valid DBCS string:
    @K1KK93K4
  10. Truncation of Pure DBCS Data
    • Truncation of the Field

      Because a pure DBCS field holds 2-byte DBCS characters of text, plus a 1-byte start field, the field length must be odd. If it is an even number of bytes, it is shortened by one byte.

      For example, if your program issues:
      VSCREEN WRITE MESSAGE 8 3 6 (PS8 FIELD K1K2K3K4
      (where 6 is the field length), it will be processed as:
      VSCREEN WRITE MESSAGE 8 3 5 (PS8 FIELD K1K2K3K4
    • Truncation of the Text
      If the field is truncated and becomes shorter than the text you are writing to it, the text is also truncated to fit the field and a message is issued. For example, the above commands write the following field:
      @K1K2
      which has a length of five. The original data, K1K2K3K4, has been truncated to fit the field.
    • Truncation of not valid DBCS Data

      When defining a PS8 field (FIELD option) or writing to a predefined PS8 field (DATA option), the text must also be an even number of bytes. If it is an odd number of bytes, it will be shortened by one byte to make it valid, with no message issued.

      For example, if your program issues:
      VSCREEN WRITE MESSAGE 8 3 0 (PS8 FIELD K1K2K
      (where K1K2K is the text), it will be processed as:
      VSCREEN WRITE MESSAGE 8 3 0 (PS8 FIELD K1K2
  11. When MIXED or SBCS is specified, both DBCS and SBCS characters may be displayed in the field, separated by 1-byte SO and SI control codes. You may insert and type over SO/SI codes in a MIXED field, but you cannot enter SO/SI codes directly from the keyboard in a SBCS field.

    If your application writes output to a mixed DBCS field that causes the field to wrap a line, an extra start field or extra SO/SI characters may be inserted on the following line(s) for the text that wraps. Allow extra space for these when you specify the field length; otherwise, truncation may occur. If you overtype a wrapped field, the extra characters are returned to the application in the changed field.

    Once you define a MIXED or SBCS field, you cannot change the field attributes without redefining the field.

    The MIXED and SBCS options are ignored if the PS8 option is also specified. If you are writing a MIXED or SBCS field on a PS8 vscreen, be sure to specify PS0 or the PSS value you want. Otherwise, PS8 is assumed, and MIXED or SBCS is ignored.

  12. Field Outlining

    You can define field outlining only when you define a field (using the FIELD option).

    Outlining may be BOXDef (the default outlining for the device), BOX (a full box), or any combination of the following to obtain the remaining 14 possible valid values:
    BOXLeft
    A vertical line on the left of the field
    BOXOver
    Overline
    BOXRight
    A vertical line on the right of the field
    BOXUnder
    Underline

    You cannot specify BOX and BOXDef with each other or with any of the other outlining values above.

    If a field is broken or wraps around a line, the outlining is the same for each partial field or line as it was for the original field. For example:
    The figure is explained in the surrounding text.
    If the above field is broken into two fields by a second field being defined, the outlining (BOXRight, BOXOver, and BOXLeft) repeats itself for the second field, as follows:
    The figure is explained in the surrounding text.
    If the field wraps around a line, the outlining (BOXRight, BOXOver, and BOXLeft) repeats on each line:
    The figure is explained in the surrounding text.

    Vertical outlining that wraps lines, as in this example, may produce the appearance of multiple fields on the screen, although only a single field is being displayed.

    Note: Currently on PS/55-family displays, for fields ending at column 80 of the physical screen that are outlined on the right (with BOX or BOXRight), the outlining on the right actually appears to the left of column 1 on the next line.
  13. When you enter the VSCREEN WRITE command and logging is in effect (SET LOGFILE command), CMS converts pure DBCS to mixed DBCS text (by adding SO/SI control codes) before putting the data into a file. This is done so you can use XEDIT to view or change the file.

    Logging does not take place until a refresh occurs.

  14. Specifying a line number of zero is valid only when writing to the scrollable area. When specifying a line number of zero and writing a field, a field is created at the line past the current bottom of the virtual screen. This provides a means for writing sequentially to the virtual screen. When doing sequential writes, a field always fills an entire line. The length of the field is determined as follows (assume a virtual screen with 80 columns):
    • If the length specified is zero, as in the example:
      vscreen write cms 0 0 0 (field Enter name:
      A field is created at the line past the current bottom of the CMS virtual screen. A start field is placed in column 1 and the text begins in column 2. All the text is written and the length of the field is set to 80.
    • If length specified is less than the number of columns in the virtual screen, as in the example:
      vscreen write cms 0 0 10
      A field is defined at one line past the current bottom of the virtual screen. Even though the length was specified as 10, the length of the field is set to 80 in order to fill the entire line.
    • If length specified is greater than the number of columns in the virtual screen, as in the example:
      vscreen write cms 0 0 100
      A field is defined at one line past the current bottom of the virtual screen. In this case, the length of the field is set to 160 and the field fills two lines.
  15. When using Option B, SET CHARMODE must be ON to update COLOR, EXTHI, and PSS. If SET CHARMODE is OFF they are ignored. Switching from SET CHARMODE ON to OFF may produce some undesirable results, such as a field having attributes you intended only for a character.
  16. When specifying a line number of zero and writing COLOR, EXTHI, PSS, or DATA, you are acting on the current field. The current field is the most recent field written to the scrollable data area of the virtual screen. The column number specifies the position in the current field. For example:
    vscreen write cms 0 5 0 (COLOR 11116666777
    will update the color buffer starting at the fifth position of the current field.
  17. If the length specified is less than the length of the text, the text is truncated. If the length specified is greater than the length of the text, the text is padded with the characteristics specified in option A. If the options are not specified, text is padded with the characteristics defined for the virtual screen.
    Note: When you are not writing a field, the text is written for the length specified or until the next field is encountered.
    For example:
    vscreen write cms 1 1 20 (blank field Enter your name:
    vscreen write cms 0 0 20 (red color 11111
    writes Enter your name:. The Enter is displayed in blue and your name: is displayed in red.
    The example:
    vscreen write cms 1 1 10 (data Enter your name:
    writes Enter your.
  18. When defining a virtual screen, the top reserved area is defined as one continuous field and the bottom reserved area is defined as one continuous field. However, the scrollable area is not defined as a field. To write to the scrollable data area, you must define a field.
  19. In a virtual screen, the lines in the top reserved area are numbered starting from the top. The top line is 1, the second line is 2, and so forth. In the bottom reserved area, lines are numbered starting at the bottom and have negative values. The bottom line is -1, the second line up is -2, the third line up is -3, and so forth.
  20. Once a field is defined, you cannot change the attributes (PROtect, NOPROtect, High, NOHigh) without redefining the field. However, you can change the extended attributes (color, exthi, psset) or data of the field. For example, suppose you define the this field:
    vscreen write cms 5 20 0 (field Enter your name:
    To change the color extended attribute, you can enter:
    vscreen write cms 5 20 0 (COLOR 2222224444455555

    As a result, beginning at line 5, column 21 (because there is a start field character in column 20), Enter will be red, your will be green, and name: will be turquoise.

  21. When writing sequentially, see Usage Note 14, and the text contains a character assigned to X'15' (end of line, or EOL) through the SET INPUT command, that character indicates a line end. The text following it is continued on the next line. A new line is written for each EOL.
  22. You should load programmed symbol sets prior to using XEDIT or prior to issuing the SET FULLSCREEN or SET FULLSCREEN RESUME commands. This ensures the programmed symbol sets are available when you use full-screen CMS or XEDIT.

    For line mode CMS, the programmed symbol sets are detected the first time you display a window or when you invoke XEDIT. If you load programmed symbol sets after you have displayed a window or after you have invoked XEDIT, you must invoke XEDIT again to ensure detection of the new programmed symbol sets.

  23. Some programs use X'1D' to effect highlighting or color attributes of output. In full-screen CMS X'1D' is a nondisplayable character and does not affect the output.

Messages and Return Codes

  • DMS622E Insufficient free storage [RC=104]
  • DMS921E Virtual screen vname is not defined [RC=28]
  • DMS923E Specified location is outside the virtual screen [RC=32]
  • DMS928E Command is not valid for virtual screen vname [RC=12]
  • DMS3952E Conflicting option option [RC=24]

Additional system messages may be issued by this command. The reasons for these messages and their location are:

Reason Location
Errors in command syntax Command Syntax Error Messages