<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <meta http-equiv="Content-Type" content="text/html; charset=utf-8"> <meta name="Copyright" content="Copyright (c) 2006 by IBM Corporation"> <title>Write to Display (QsnWTD) API</title> <!-- Begin Header Records ========================================== --> <!-- All rights reserved. Licensed Materials Property of IBM --> <!-- US Government Users Restricted Rights --> <!-- Use, duplication or disclosure restricted by --> <!-- GSA ADP Schedule Contract with IBM Corp. --> <!-- DSMMST1 SCRIPT A converted by B2H R4.1 (346) (CMS) by V2KEA304 --> <!-- at RCHVMW2 on 29 Jan 1999 at 16:05:09 --> <!-- Change History: --> <!-- YYMMDD USERID Change description --> <!--File Edited November 2001 --> <!--End Header Records --> <link rel="stylesheet" type="text/css" href="../rzahg/ic.css"> </head> <body> <a name="top_Of_Page"></a> <!-- Java sync-link --> <script language="Javascript" src="../rzahg/synch.js" type="text/javascript"> </script> <h2>Write to Display (QsnWTD) API</h2> <div class="box" style="width: 70%;"> <br> Required Parameter Group:<br> <!-- iddvc RMBR --> <br> <table width="100%"> <tr> <td align="center" valign="top" width="10%">1</td> <td align="left" valign="top" width="50%">Control character byte 1</td> <td align="left" valign="top" width="20%">Input</td> <td align="left" valign="top" width="20%">Char(1)</td> </tr> <tr> <td align="center" valign="top">2</td> <td align="left" valign="top">Control character byte 2</td> <td align="left" valign="top">Input</td> <td align="left" valign="top">Char(1)</td> </tr> </table> <br> Omissible Parameter Group:<br> <!-- iddvc RMBR --> <br> <table width="100%"> <tr> <td align="center" valign="top" width="10%">3</td> <td align="left" valign="top" width="50%">Command buffer handle</td> <td align="left" valign="top" width="20%">Input</td> <td align="left" valign="top" width="20%">Binary(4)</td> </tr> <tr> <td align="center" valign="top">4</td> <td align="left" valign="top">Low-level environment handle</td> <td align="left" valign="top">Input</td> <td align="left" valign="top">Binary(4)</td> </tr> <tr> <td align="center" valign="top">5</td> <td align="left" valign="top">Error code</td> <td align="left" valign="top">I/O</td> <td align="left" valign="top">Char(*)</td> </tr> </table> <br> Returned Value:<br> <!-- iddvc RMBR --> <br> <table width="100%"> <tr> <td align="center" valign="top" width="10%"></td> <td align="left" valign="top" width="50%">Return code</td> <td align="left" valign="top" width="20%">Output</td> <td align="left" valign="top" width="20%">Binary(4)</td> </tr> </table> <br> Default Public Authority: *USE<br> <!-- iddvc RMBR --> <br> Service Program: QSNAPI<br> <!-- iddvc RMBR --> <br> Threadsafe: No<br> <!-- iddvc RMBR --> <br> </div> <p>The Write to Display (QsnWTD) API issues a Write to Display (WTD) command. A WTD command is used to indicate the beginning of a series of output operations. For most of the DSM screen output operations, the control unit requires that a WTD be issued prior to the actual operation itself, in the same I/O operation. Multiple output operations can be sent with a given WTD command by using a command buffer. For direct operations, such output APIs, implicitly issue a WTD command. For indirect operations, a WTD is added to the buffer if one does not exist already. Each time a WTD command is received, the control unit implicitly sets the display address to row 1, column 1, prior to issuing the operation.</p> <p>For example, if two direct QsnWrtDta operations are performed in succession and the second operation does not specify the row and column parameters, the data is written to row 1, column 1, and not the display address following the first QsnWrtDta operation. If two indirect QsnWrtDta operations are issued to an empty command buffer, the first QsnWrtDta operation causes a WTD command to be added to the buffer, but the second QsnWrtDta operation can use the existing command. In this case, if no row and column are specified, the display address used for the second operation will be the one after the first operation is issued. If an intervening operation that does not require a WTD, such as a QsnClrScr or a QsnSetErr, is added to the command buffer between two operations that do require a WTD command, a second WTD command is added to the buffer for the second operation.</p> <p>The screen output APIs that require a WTD command and that correspond to the WTD command <strong>orders</strong> (as described in 5250 Functions Reference, SA21-9247) are as follows:</p> <blockquote> <p>Set Output Address (QsnSetOutAdr)</p> <p>Write Data (QsnWrtDta)</p> <p>Write Transparent Data (QsnWrtTDta)</p> <p>Pad for N Positions (QsnWrtPad)</p> <p>Pad between Two Screen Addresses (QsnWrtPadAdr)</p> <p>Set Field (QsnSetFld)</p> <p>Set Cursor Address (QsnSetCsrAdr)</p> <p>Insert Cursor (QsnInsCsr)</p> </blockquote> <p>The cursor position is not affected if the keyboard is unlocked when command processing begins and is not locked during command processing, or if a parameter error is detected. If specified by control character byte 1, the cursor will be moved to the insert cursor or default location when the keyboard is unlocked.</p> <p>This operation corresponds directly to the 5250 Write to Display command. If this is an indirect operation, this operation will issue a new WTD command to the command buffer.</p> <br> <h3>Authorities and Locks</h3> <p>None</p> <br> <h3>Required Parameter Group</h3> <dl> <dt><strong>Control character byte 1</strong></dt> <dd>INPUT; CHAR(1) <p>The operation for the display to perform prior to processing the Write to Display command. See <a href="dsm1e.htm#HDRCC">Control Characters</a> for a description of the control character values.</p> </dd> <dt><strong>Control character byte 2</strong></dt> <dd>INPUT; CHAR(1) <p>The operation for the display to perform after the Write to Display command has been processed. See <a href="dsm1f.htm#HDRCC">Control Characters</a> for a description of the control character values.</p> </dd> </dl> <br> <h3>Omissible Parameter Group</h3> <dl> <dt><strong>Command buffer handle</strong></dt> <dd>INPUT; BINARY(4) <p>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 command is sent to the display. Otherwise, this is an indirect operation and the command is stored in the command buffer without an I/O operation taking place.</p> </dd> <dt><strong>Low-level environment handle</strong></dt> <dd>INPUT; BINARY(4) <p>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.</p> </dd> <dt><strong>Error code</strong></dt> <dd>I/O; CHAR(*) <p>The structure in which to return error information. For the format of the structure, see <a href="../apiref/error.htm#hdrerrcod">Error Code Parameter</a>. If this parameter is omitted, diagnostic and escape messages are issued to the application.</p> </dd> </dl> <br> <h3>Returned Value</h3> <dl> <dt><strong>Return code</strong></dt> <dd>OUTPUT; BINARY(4) <p>A return code indicating the result of the operation. The value returned will be 0 if the operation was successful, or -1 otherwise.</p> </dd> </dl> <br> <h3>Error Messages</h3> <table width="100%" cellpadding="3"> <!-- cols="15 85" --> <tr> <th align="left" valign="top">Message ID</th> <th align="left" valign="top">Error Message Text</th> </tr> <tr> <td align="left" valign="top">CPF24B4 E</td> <td valign="top">Severe error while addressing parameter list.</td> </tr> <tr> <td align="left" valign="top">CPF3CF1 E</td> <td valign="top">Error code parameter not valid.</td> </tr> <tr> <td align="left" valign="top">CPF3CF2 E</td> <td valign="top">Error(s) occurred during running of &1 API.</td> </tr> <tr> <td align="left" valign="top">CPFA301 E</td> <td valign="top">Command buffer is full.</td> </tr> <tr> <td align="left" valign="top">CPFA303 E</td> <td valign="top">Error occurred for screen I/O operation.</td> </tr> <tr> <td align="left" valign="top">CPFA304 E</td> <td valign="top">Data-stream error &1 reported for screen I/O operation.</td> </tr> <tr> <td align="left" valign="top">CPFA305 E</td> <td valign="top">Cannot add operation to command buffer.</td> </tr> <tr> <td align="left" valign="top">CPFA31C E</td> <td valign="top">Incorrect value for control character byte &1.</td> </tr> <tr> <td align="left" valign="top">CPFA31E E</td> <td valign="top">Required parameter &1 omitted.</td> </tr> <tr> <td align="left" valign="top">CPFA331 E</td> <td valign="top">Buffer handle incorrect.</td> </tr> <tr> <td align="left" valign="top">CPFA334 E</td> <td valign="top">Low level environment handle incorrect.</td> </tr> <tr> <td align="left" valign="top">CPFA343 E</td> <td valign="top">Output operation not done.</td> </tr> <tr> <td align="left" valign="top">CPFA344 E</td> <td valign="top">The file &2 in library &3 is not valid.</td> </tr> <tr> <td align="left" valign="top">CPFA345 E</td> <td valign="top">The invite active flag is not valid.</td> </tr> </table> <br> <hr> API introduced: V2R3 <hr> <center> <table cellpadding="2" cellspacing="2"> <tr align="center"> <td valign="middle" align="center"><a href="#Top_Of_Page">Top</a> | <a href= "dsm.htm">Dynamic Screen Manager APIs</a> | <a href="aplist.htm">APIs by category</a></td> </tr> </table> </center> </body> </html>