Transaction Connection

About This Book

This book provides technical information for using Transaction Connection (TC). It describes the script language that you use to pass information between DCConnect and a host system, database(s) or XML-based application. Following a discussion of general data collection concepts is a reference for the commands in the script language. At the end is a description of the messages that TC might generate.

This section provides general information about how to use this online book, as well as the legal notices, service marks, and trademarks used in this book.

To receive information about a topic that is highlighted, click on it:

• Notices
• Trademarks and Service Marks

Notices

Last Update (January 2024)

References in this documentation to IBM products, programs, or services do not imply that IBM intends to make these available in all countries in which IBM operates. Any reference to an IBM product, program, or service is not intended to state or imply that only IBM's product, program, or service can be used. Any functionally equivalent product, program, or service that does not infringe upon any of IBM's intellectual property rights or other legally protectible rights can be used instead of the IBM product, program, or service. Evaluation and verification of operation in conjunction with other products, programs, or services, except those expressly designated by IBM, are the user's responsibility.

IBM may have patents or pending patent applications covering the subject matter in this documentation. The furnishing of this publication does not give you any rights to these patents. You can inquire, in writing, to:

IBM Director of Licensing
IBM Corporation
500 Columbus Avenue
Thornwood, NY  10594
U.S.A.

For online versions of this documentation, we authorize you to:

• Copy, modify, and print the documentation contained on the media, for use within your enterprise, provided you reproduce the copyright notice, all warning statements, and other required statements on each copy or partial copy.
• Transfer the original, unaltered copy of the documentation when you transfer the related IBM product (which might be either machines you own, or programs if the programs' license terms permit a transfer). At the same time, you must destroy all other copies of the documentation.

You are responsible for payment of any taxes, including personal property taxes, resulting from this authorization.

THERE ARE NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

Some jurisdictions do not allow the exclusion of implied warranties, so the above exclusion might not apply to you.

Your failure to comply with the terms above terminates this authorization. Upon termination, you must destroy your machine-readable documentation.

Trademarks and Service Marks

The following terms are trademarks of the IBM Corporation in the United States or other countries or both:

IBM	Transaction Connection
OS/2	Operating System/2
MAPICS	Presentation Manager
DB2

Other company, product, and service names may be trademarks or service marks of others.

Windows is a trademark of Microsoft Corporation.

Transaction Connection Overview

The Transaction Connection (TC) program is a is a script-based data collection transaction processing program which make it easy to integrate with:

• Data collection terminals controlled by the DCConnect program

• An IBM DB2 database or one or more databases accessed via ODBC (including DB2)

• A 3270, 5250, or ASCII/ANSI host application screen

• An XML message-based system

• Another Transaction Connection session using data requests

TC can connect to any combination of these systems at one time and pass data in any direction among them. You write TC scripts containing commands to format, process and route data.

Unique TC scripts can be defined for each transaction type that must be handled; TC scripts can also be set up to handle the movement of data between otherwise unconnected systems.

For example, a worker at a data collection terminal can press a function key, scan a few bar codes in response to input prompts, and create a transaction that is routed through DCConnect and TC to the relational database and/or the host application screen. Query results or host application responses can be routed back to the operator at the terminal. All of this happens without the operator being required to log-on, navigate menus and windows, or know how to handle application errors.

For the part of the application involving the relational database, basic database inserts, updates, and queries can be developed and up and running in production in very little time. Also, the power and flexibility are available to be as elaborate with the SQL as you want to be -- again with a fraction of the effort required to write SQL from scratch, and with the performance of having a compiled C program performing your dynamic SQL.

For the host application screen manipulation, your script, consisting of high-level commands, is used to automate the function of a data entry operator. Once you train the system with your script of actions to be taken for each type of transaction, your Transaction Connection scripts will work tirelessly and without any keystroke errors as it intelligently transcribes data to the host application.

Transaction, Remote Validation, or Data Request Modes

A TC session can be run in one of three modes: Transaction, Remote Validation, or Data Request mode. In any mode, you can perform database inserts, updates, and queries, and/or host screen manipulations using the data from the DCT.

Transaction Mode

Transaction mode requests data transactions from a DCConnect mailbox, processes the data as you have specified in your script command file, and finally releases the transaction from the DCConnect mailbox. The TC session operates in Transaction mode if the mailbox specified on the command line or in the script files is any name except REMOTE_VALIDATION or DATA_REQUEST, and the mailbox matches one configured in DCConnect.

Each TC session that is running in Transaction mode can receive and individually process transactions from up to 50 function groups, with each function group having up to 121 unique scripts for each possible key event (F1, F2, ..., PF1, PF2, ...)

Alternately, instead of identifying script processing based on function group and key event (using StartFunctionGroup/StartKey), you can base it on a portion of the received data using the StartMatch statement. Typically the first 3 to 5 characters of the data would be an identifier that must match one of the StartMatch statements in the script being processed. Regardless of the number of characters you choose, it is recommended that you use that number for all scripts in order to avoid problems where the characters of one ID are a subset of another ID.

Remote Validation Mode

In Remote Validation mode, the TC session informs DCConnect of a list of validation file names that it will be handling. Each time a DCT sends a remote validation request to DCConnect that matches one of these validation file names, DCConnect routes the validation request to this TC session for validation and response. In this case, the file names do not refer to an actual file, but the name is used as the identification of the validation required for the incoming data.

The TC session operates in Remote Validation mode if it has been started with REMOTE_VALIDATION specified as the mailbox. Then, in your command script file, instead of specifying a terminal event (for example, F1, F2, and so forth) in a StartKey command, you specify the validation file name in a StartVal command.

The TC session determines the list of validation files from all of the StartVal() statements in the script it is processing.

A single TC session can handle processing for up to 125 remote validation files. You may start as many remote validation sessions of TC as you need and that your system can handle. Use of the mailbox REMOTE_VALIDATION repeatedly for these sessions is an exception to the rule about requiring unique mailboxes for each TC session.

A typical method of actually performing the remote validation is to perform a query (SELECT statement) that yields either no rows or one or more rows of resulting report data. This provides the information necessary to determine if the data being verified is present or absent in the system. The Perform_Select or Perform_Fetch commands allow you to branch to the appropriate step if no rows were found or to fall through to another step if one or more rows were found. Refer to the example Handling Remote Validation Request.

Data Request Mode

Data requests can be made in a several different ways:

• By a DOS or Windows PC running an application that uses the "Terminal Services for DOS and for Windows" API. Applications using the API provided by that product can issue the API call DwsRequestData to generate a data request.
• By a custom application running on the same PC as DCConnect. The DCConnect API provides the function DcxRequestData for the purpose of allowing applications to make data requests.
• By another TC session. The script command set includes the command:

        Make_Data_Request()
  

  that translates to a DcxRequestData API call. This command can be used whether or not the TC session is processing transactions, validation requests, data requests, or no DCConnect data.

A TC session could be set up as a kind of server for other TC sessions to allow them to communicate with each other indirectly. The 'server' TC session would set itself up in data request mode to allow all the other TC sessions to communicate with it, regardless of what mode they are running in.

No matter where the data request originated, it contains the name of the application that is supposed to service the request. This is the application name that DCConnect uses to route the request to the proper server. It is the name that must be specified by the 'server' TC session as the <application> parameter or in the Application script command.

The TC session operates in Data Request mode if it has been started with the keyword DATA_REQUEST being specified as the mailbox name, either on the command line for the <mailbox> parameter or in the script using the mailbox() command. In Data Request mode, you must specify the application name in the command file or on the command line.

You can start as many data request TC sessions as you need and that your system can handle. For each, the mailbox parameter always is DATA_REQUEST. However, the application name used by each session must be unique.

When in Data Request mode, you cannot use the StartKey/StartVal/StartCluster commands or the corresponding End commands. You must use StartMatch / EndMatch blocks to divide up the processing of the data requests. You should ensure that all possible kinds of data requests that are handled by the TC session are unique in some portion of the data. It is recommended that the first one or more characters of the data be used for identifying the type of request. Regardless whatever number of characters you choose, use that number for all scripts in order to avoid problems where the characters of one ID are a subset of another ID.

When in Data Request mode, each request that is received contains the following data parts, accessible through the Set / Append_UV_Xact_Data command and other commands that access data parts:

    DATALEN
    TXNDATA
    ORIGINATOR
    TERM_NAME
    TXNFIELD1

The data parts ORIGINATOR and TERM_NAME are synonymous. The term ORIGINATOR is used because data requests, unlike transactions or validation requests, may originate from another application rather than from a terminal. The term ORIGINATOR covers both terminals and applications, although using TERM_NAME works even if the originator is not a terminal.

Even those data requests that do originate from a terminal, do so from a special kind of terminal, the DCConnect DOS and Windows terminal. These terminals can generate only data requests, transaction and validation requests; they cannot process commands initiated by other applications - with the exception of Set_Term_UV_Data/Send_Named_Term_UV_Data/Send_Term_Data. All other terminal-related script commands are not to be used for the originator of a data request.

The data portion of the data request can be up to 16383 bytes in length. Because the data request can be much larger than most of the user variables (235 bytes), several of the user variables can accommodate data up to 16383 bytes. By default the user variables in the range 241-250 are automatically allocated for 16383 bytes if they are referenced any where in the script. These user variables can be treated just like the other user variables; they are just longer than the others.

Note: The total number of user variables and the number of large user variables can be changed by using the Define_UVs command. The size of large user variables can be changed using Define_Large_UV_Size command.

After a data request is received, the script must do one of two things:

Build a reply for that request

This can be done in one of the large user variables - or even a smaller one if the reply does not exceed 235 bytes. When the reply has been built, the script command: Reply_To_Data_Request() can be used to send the reply to the originator of the request. This command specifies the user variable that contains the reply and an optional label to branch to if the reply is not sent successfully.

Forward the data request to another application

Using the command: Forward_Data_Request() to specify the name of an application to which the current data request should be given. That application must currently be registered with DCConnect in order for the forward operation to be successful. This command takes one parameter, the target application name. This application name can even be the same application (the current TC session), in which case the request is added to the end of the queue of outstanding requests for this application.

Routing Incoming Transactions/Requests for Processing

Your incoming transactions, remote validation requests, web service requests, and data requests are sorted and routed along the way by each layer of the system.

• At the terminal, your transaction programs determine the transaction identifier (key or event ID) or remote validation file name and the content of the data packet being sent.

• For data requests, the originating terminal or application must build the request that can be uniquely identified as to what type of request is being built.

• At DCConnect, the configuration of your mailbox determines which applications get a copy of each incoming transaction.

  For validation and data requests, the DCConnect mailbox configuration is not relevant.

• The command line parameters used to start each TC session provide the DCConnect mailbox name to be opened by this session. (Alternately, the Mailbox command can be specified within the TC script).

• In your script file, the use of StartCluster, StartKey, StartVal, and StartMatch commands determines how to do the final sorting.

The various Start... commands allow you to customize processing of many types of incoming data. TC sorts each transaction, remote validation requests, web service requests, or data requests as follows.

• For transaction mode:
  1. All data-matching comparisons are made, as defined in your StartMatch commands. The first match found will be executed.
  2. If no match was found, the originating terminal function group is compared against all StartFunctionGroup commands. If a function group was defined in the script, the transaction ID (key or event ID) of the transaction is used to find the right StartKey command within that function group.
  3. If a function group was found, or no appropriate StartKey statement was found within the function group, the default function group set of StartKey statements is searched for a match with the incoming key/event ID. If again, no appropriate StartKey statement is found, an error is reported.
  4. Web service requests are routed purely based on the web service name in the Start_WS command

• For remote validation mode:

  1. All data-matching comparisons are made, as defined in your StartMatch commands. The first match found will be executed.

     Note: In order for the TC session to register for receiving remote validation requests from DCConnect, there must be a StartVal command used in the script with the corresponding DCConnect validation file name as the parameter. There must be at least one valid command in the StartVal / EndVal script, but the data sorting can be set up such that this script is never executed.

  2. If no StartMatch commands were found to be appropriate, the StartVal script matching the incoming request's validation file name is executed.

• For data request mode:

  1. Only StartMatch commands can be used to sort the data request; StartFunctionGroup/StartKey/StartVal commands are not allowed in this mode. You should ensure that all possible kinds of data requests that are handled by the TC session are unique in some portion of the data. It is recommended that the first one or more characters of data be used for identifying the type of request. It is recommended that you use the same number of bytes for comparison in all StartMatch commands so that you do not have the problem where the matching string for one StartMatch command is a subset of another StartMatch command.

Running Scripts Based on Time-Related Events

You can define scripts to be run based on various time-related events:

• Using StartTime, you can specify up to 124 distinct times during the day at which you want a script to be run. For example, this can be a time when you want a TC session to extract a report from the database, or a time at which you want it to cease processing transactions for some delay period so a database backup can be performed.

  Processing of a time-of-day scripts has the highest priority of any event; however, a time-of-day event does not preempt another script that is already running when the specified time occurs. Time-of-day events which could not be run at the designated time are queued for processing as soon as the currently running script completes.

  Note: All of the StartTime scripts are stored internally with one of the 50 clusters that can be allocated. If at least one StartTime block is included in your scripts, only 49 clusters are available for other StartCluster blocks.

• StartInterval can be used to specify a scripts you want to have run periodically, no matter what the transaction volume from the terminals may be.

  Processing of an interval script has the second-highest priority after time-of-day events. A single interval event that could not be run when the designated interval elapsed is queued for processing as soon as TC has completed the script already in progress and has completed any time-of-day events that are queued.

• StartTimeout specifies the script you want to have run if the specified amount of time elapsed without receiving any data from any terminal or application. Each incoming transaction, validation request or data request resets this timer to the full value again.

  As with all transactions, remote validation requests, or data requests, timeout scripts have the lowest priority to run (after time-of-day and interval scripts).

  Note:

  The script command Max_Xact_Wait must be located somewhere in the script to specify how much time must elapse before the timeout script is run. If this command is not specified anywhere, the timeout script does not run. All of the StartTime scripts defined are stored internally with one of the function groups that can be allocated. Therefore, if at least one StartTime block is included in a script, only 49 function groups are available for other StartFunctionGroup blocks.

Elements of the TC Script Language

This section describes various data elements and control features that are used to create scripts for processing your transactions, validation requests and data requests.

Using White Space, Blank Lines and Comments in TC Scripts

When entering commands in TC scripts, the following rules apply:

• White space characters (spaces and tabs) may be added anywhere on a line, between words and symbols.

• Blank lines can be added anywhere in the file

• Commands that contain one or more parameters can be split across multiple lines as long as the opening parenthesis is on the same line on which the command starts. TC looks for the opening and closing parentheses to determine when it has a complete command. It ignores parentheses found in literal strings and comments. For example:

     if ((uvRow #< 1)  || 
         (uvRow #> 16) ||
         (uvCol #< 1)  ||
         (uvCol #> 20))
       Goto InvalidDimensions
   
     Call UpdateScreen(uvText,
                       uvRow,
                       uvCol)
  

• A command can be split anywhere an extra space might normally be added for padding between complete words and symbols. Do not split a literal string (enclosed in double quotes) across multiple lines.

• A comment may be entered on a line by itself by starting the line with double slashes (//). White space characters may precede the double slashes.

• Comments may also be added to the ends of lines that contain commands, even if the line has only part of a command. For example:

     if ((uvRow #< 1)  ||                  // Screen dimensions are
         (uvRow #> 16) ||                  // 16 rows by 20 columns
         (uvCol #< 1)  ||
         (uvCol #> 20))
       Goto InvalidDimensions
   
     Call UpdateScreen(uvText,             // Text to show on the screen
                       uvRow,              // Row on which to put the text
                       uvCol)              // Column at which to start the text
  

• TC has 1024 byte buffer for storing commands as they are read in from one or more lines. As TC reads in a line, it strips leading and trailing white space and trailing comments before adding the data to the 1024 byte buffer. A single space is added between each line of data that is added to the buffer.

User Variables

1. Global user variables, which are accessible from any script at any time

2. Local user variables, which may be manipulated only by the script in which they are defined.

By default TC allows you to define up to 250 global user variables for your use to accumulate and store data. The total number of user variables can be changed using the Define_UVs command.

Being global means that they are accessible from all places in the execution of the command file, and that they are never automatically cleared or changed (except on start-up of the session). When in doubt about the contents of a user variable, useClear_UV to reset the user variable.

Each of the user variables is always referred to by name, not by a plain number. The default names are UV1 through UV250, but you can give them more meaningful aliases by using the Name_UV command.

  Name_UV( UV1,     uvBadgeNumber )    // uvBadgeNumber is alias for UV1
  Name_UV( NEXT_UV, uvRow         )    // uvRow         is alias for UV2
  Name_UV( NEXT_UV, uvCol         )    // uvCol         is alias for UV3

Many commands require you to provide the name (UVn format, or your own chosen alias) of a user variable to be used as a target for the output of a command. For example:

  Append_UV_Host_Data( UV1, 12, 25, 10 )

tells TC to copy 10 characters starting at row 12, column 25 from the host application screen to the UV1 storage.

Other commands allow you to specify either a constant or the current value of a user variable to be used as an input to the command. For example, if you wanted to copy information from the host screen but you wanted to specify which row to copy from dynamically, you could do:

  Append_UV_Host_Data( UV1, UV2, 25, 10 )

where UV2 has a value that can be interpreted as an integer row number.

Using the aliases assigned above, you could alternatively write this as:

  Append_UV_Host_Data( uvBadgeNumber, uvRow, uvCol, 10 )

TC creates storage for as many user variables as you reference in your script, up to the defined maximum. Even if the user variables used are not consecutive, only the minimum amount of storage is allocated.

By default, user variables 1 through 240 are 235 characters long, and have no particular data type (you can store integers, real numbers, or character strings in them). And by default, user variables 241 through 250 have the same characteristics except that they are 16383 characters long. These large user variables are useful when processing or making data requests because data requests and their replies can be up to 16383 characters long. If you do not handle data greater than 235 characters, you should not use variables 241-250. This helps conserve your PC's resources.

You can change the total number of user variables available as well as the number of large user variables using the Define_UVs command.

In addition to the usual global user variables ( named user variables and UVn references) you can declare local user variables within a StartMatch / EndMatch, StartTime / EndTime etc. block or within a subroutine. Local user variables are created using the Declare command:

  DECLARE ( localUVName )

You can have local user variables with the same name in many routines -- they each have their own storage area. Local user variables may not, however, have the same name as any global user variable which has already been named via the Name_UV command, nor have a name like 'UV12' which would be confused with a basic global user variable name. It is recommended that you use a naming convention (say, a leading 'g' on all global user variables) in order to keep things straight and to avoid any compile errors.

Local user variables are the same size as 'regular' global user variables (235 characters). If you need a long user variable (16KB unless redefined) you will need to use a suitably defined large global user variable.

There are several commands that can be used to affect the contents of the local/global user variables:

• Append_UV_Select_Data (or Set_UV_SelectData) appends to a user variable from an SQL SELECT statement's results table.
• Append_UV_Kbd_Data / Append (or Set_UV_Kbd_Data / Set) appends to a user variable from a constant string typed into your script file.
• Append_UV_Host_Data (or Set_UV_Host_Data) appends to a user variable from data copied from the host screen.
• Append_UV_Xact_Data (or Set_UV_Xact_Data) appends to a user variable from data in a transaction, validation request or data request.

  Note: This command can also be used to copy one user variable to another.

• Append_UV_UV (or Set_UV_UV) appends to a user variable from another user variable.
• Clear_UV clears a user variable.
• Define_UVs allows you to define how many user variables are available and how many of those are of the large size.
• Define_Large_UV_Size allows you to redefine the size of large user variables - up to 64Kb instead of the default of 16kb.
• Get_Application_List gets the list of valid applications in the DCConnect configuration.
• Get_Job_List gets the list of valid jobs in the DCConnect configuration.
• Get_Length gets the length of some data from the current transaction record or of a user variable and stores that length in a user variable.
• Get_Mailbox_List gets the list of valid mailboxes in the DCConnect configuration.
• Get_Term_List gets the list of valid terminals in the DCConnect configuration. The list can also be limited to a specific job.
• Get_Term_UV_Data retrieves the value of a DCT user variable and copies it to the user variable.
• Send_To_Host send the contents of a user variable to the specified row and column on the host screen, and moves the cursor as desired.
• Send_Host_UV_Data copies all or part of a TC user variable to the current cursor position on the host screen.
• Send_Term_UV_Data sends the contents of a TC user variable to a DCT user variable.
• Format_UV formats a user variable for use with a specific column type of the database table. This is especially useful when free-form SQL is being used.
• Load_UVs loads the previously-saved contents of UV1-20 for the current terminal.
• Save_UVs saves the current contents of UV1-20 for the current terminal to a disk file.
• UV_Math allows you to perform arithmetic functions on the contents of the user variable. You can add, subtract, multiply, or divide the current contents of the user variable using the contents of another user variable or a constant value, and cause the result to be formatted as an integer or real number to any width or precision desired.
• Append_UV_Ctrl_ID (or Set_UV_Ctrl_ID) appends to a user variable the currently defined controller ID character.
• Append_UV_Seq_Num (or Set_UV_Seq_Num) appends to a user variable from the sequence number maintained by the TC session.
• Delay can use a value from a user variable.
• If blocks can be processed based on the contents of user variables.
• Make_Data_Request uses one user variable for the request data and another for the reply data.
• Reply_To_Data_Request uses a user variable for the reply data to be sent.
• System can use the contents of a user variable for the command to execute.

Data Parts

TC provides descriptive names for various data parts that are predefined for your use. These parts can be distinct elements of the incoming transaction, remote validation request, data request, or the TC user variables. Many commands require that you specify a data part name as one of their parameters.

The predefined names allowed are shown in Data Parts You Can Use. Some names are only valid when executing in Transaction Mode. Others are valid only in Remote Validation Mode, while others are valid in only Data Request mode. The remainder can be used in either mode.

Table of Data Parts

Default 4 for transaction, but can be longer.
Max is 4 for validation
Max is 5 for data request

TXNFIELD1 to
TXNFIELD1024

Using Environment Variables in TC Commands

TC supports the use of environment variables in certain TC commands. An environment variable is specified by using opening and closing percent signs (%) around the environment variable name. For example:

• %TC2%

• %SystemRoot%

• %DCCONN%

For the following TC commands:

• Current_Dir

• Imbed

• Log_Data

• Log_Xact

• Open_File_Data

• Submit_Client_Files

• Submit_Validation

• WS_ToFile

• XML_LoadLoggingParameters

• XML_ToFile

 
  Open_File_Data(uvRC, "%SystemRoot%\tc2out.log")
 

 
  C:\WINNT\tc2out.log
 

TC will also look for environment variables in the command line parameter that is the top level script file name. However, chances are the operating system will have already resolved any environment variables that are specified on the command line; so TC will not have to do it.

For the commands:

• Open_File_Data

• Log_Data

The following commands:

• Append_UV_Kbd_Data / Append

• Set_UV_Kbd_Data / Set

Script Control Using If/Else

TC supports use of If-then-Else-then types of flow-of-control constructions, much like traditional programming languages. The If/Else construct can take many forms, and is best explained with some examples:

  // A simple If statement
  // Command A is executed only when the first 3 characters of
  // user variable 1 are equal to 'ABC'
  // Command B is always executed.
 
  If ( UV1(0, 3) == "ABC")
    Command A
 
  Command B
 
  // Execute several statements enclosed with braces if the
  // condition is true.  Again, Command B is always executed.
 
  If ( UV1(0, 3) == "ABC")
   {
    Command A
    Command AA
    Command AAA
   }
 
  Command B
 
  // Execute several statements enclosed with braces if the
  // condition is true.  This time, use Else to cause Command B
  // and Command BB to be executed only when the If condition was false.
 
  If ( UV1(0, 3) == "ABC")
   {
    Command A
    Command AA
    Command AAA
   }
  Else
   {
    Command B
    Command BB
   }
 
  // Nest several levels of Ifs and brace sets to structure the
  // flow of execution.
  // Execute commands A and AA when the first If is true; when
  // the second If is also true, execute commands AAA and AAAA.
  // Finally, drop through the Else statement and the statements
  // below it, until you get down to Command D (which is always executed).
  //
  // When the first If is false, skip down to the matching Else
  // statement and execute the third If statement -- if it is true,
  // execute commands B and BB, if it is false, execute
  // Command C.
  // Command D is always executed in this example.
 
  If ( UV1(0, 3) == "ABC")
   {
    Command A
    Command AA
    If ( UV2(0, 3) >= TIME(0, 6))
     {
      Command AAA
      Command AAAA
     }
   }
  Else
    If ( "1200" < TIME(0, 4) )
     {
      Command B
      Command BB
     }
    Else
      Command C
 
  Command D

When an opening brace { is the next statement after an If or Else, all commands between that opening brace and the matching closing brace belong to that If or Else statement. The statements that belong to an If or Else statement are executed whenever the If or Else condition is true.

If the next statement after an If or Else is a regular command (instead of an opening brace), only that command belongs to the If or Else. Subsequent commands either belong to a higher-level If or Else, or belong at the main level of your script.

You can have up to 50 levels of nested brace sets in effect at one time in your script.

For more information about the If statement please see If.

For information about using AND, OR and NOT operators in an If statment, please see Using AND, OR and NOT operators in If and While Statements.

Script Control Using Do...While

TC supports use of the Do...While type of flow-of-control constructions, much like traditional programming languages. For example, if you wanted to print 10 lines of underscore characters on a paper form for the worker, you could use If/Else logic:

    Append_UV_Kbd_Data( UV20, "___________________________________"
    UV_Math( UV1, =, 1 )
 
  PRINT_ANOTHER_LINE:
    Log_Data( REPORT, UV20, APPEND )
    UV_Math( UV1, +, 1)
    IF ( UV1 #<= "10")
      Goto PRINT_ANOTHER_LINE

Using Do...While logic saves some typing, and yields a more structured script:

  Append_UV_Kbd_Data( UV20, "___________________________________"
  UV_Math( UV1, =, 1 )
 
  Do
   {
    Log_Data( REPORT, UV20, APPEND )
    UV_Math( UV1, +, 1)
   }
  While ( UV1 #<= "10")

For more information about the While statement, please see While (Do...While).

For information about using AND, OR and NOT operators in an If statment, please see Using AND, OR and NOT operators in If and While Statements.

Using AND, OR and NOT operators in If and While Statements

First a few quick examples:

 
  // Make sure the dimensions are valid.  Note the command
  // is split across multiple lines and comments are included
  // at the end of each of those lines.
  if ((uvRow #< "1") OR (uvRow #> "16")  OR   // Dimensions of
      (uvCol #< "1") OR (uvCol #> "20"))      // terminal are 16x20 
    Goto InvalidDimensions
 
  // This illustrates the use of multiple levels of comparison
  // prioritized using parentheses
  if (((UV1 == "1") and (UV2 == ")") and not (UV3 != "ABC") and (UV4 == UV14)) OR
     ((UV5 == UV6) and (UV7 == UV17)))
    Goto Error
 
  // The following loop should execute only 3 times
  Set_UV_Kbd_Data(uv50, "5")
  Set_UV_Kbd_Data(uv51, "Green")
  do
   {
    Log_Error("You should see this 3 times")
    UV_Math(uv50, -, 1)
    if (uv50 #== "2")
      Set_UV_Kbd_Data(uv51, "Red")
   }
  while ((uv50 #> "0") && (uv51 == "Green"))
 

The following statements describe what syntax rules must be followed when using these operators and describe how TC processes these statements.

• The entire statement (after the word If/While) must be enclosed within a single set of parentheses.

• Each comparison operation (e.g. UV1 == "1") must be enclosed in a set of parentheses.

• The number of opening and closing parentheses must match (ignoring any parentheses that are part of a literal string or a comment).

• Any number of spaces and tabs can be included in the If/While statement.

• The If/While statement can span multiple lines. TC looks for the closing parenthesis that matches the opening parenthesis in order to determine when it has a complete If/While statement. The command can be split any where you might normally add a space for padding; it can't be split in the middle of a word or symbol or in the middle of a literal string (enclosed in double quotes).

• Comments (starting with //) can be used at the end of each line, even when the If/While statement spans several lines.

• TC has an internal buffer of 1024 bytes to store a single If/While command. As TC reads in an If/While statement that spans several lines, it strips out leading and trailing white space and comments as it stores each line in the command. A single space is kept between each line of data.

• The symbols AND, && and & can be used for the AND operation. Regardless of which symbol is used, TC will always show the single & for the AND operation in an execution trace.

• The symbols OR, || and | can be used for the OR operation. Regardless of which symbol is used, TC will always show the single | for the OR operation in an execution trace.

• The symbols NOT and ! can be used for the NOT operation. Regardless of which symbol is used, TC will always show the ! for the NOT operation in an execution trace.

• If using the words AND, OR and NOT instead of the symbols, you can specify these words in upper, lower or mixed case.

• If using the words AND or OR, the previous character must be white space or a closing parenthesis. The following character must be white space, an opening parenthesis or the NOT operator symbol !.

• If using the word NOT, the previous character must be white space, an opening parenthesis or the & or | operator. The following character must be white space or an opening parenthesis.

• You can specify multiple AND or OR operations in the same set of parentheses. For example: If ((C1) && (C2) && (C3) && (C4)) - where C1, C2, ..., C4 are each comparison operations such as uvColor == "Green".

• The AND and OR operators can be immediately followed by a NOT operator. For example: While ((C1) && !((C2) || (C3)))

• An opening parenthesis can only be preceded by one of the following:

  • White space

  • Another opening parenthesis

  • A NOT / ! operator

  • An OR / || / | operator

  • An AND / && / & operator

  The opening parenthesis must be the first non-white space character after the If/While keyword.

• A closing parenthesis can only be preceded by one of the following:

  • White space

  • Another closing parenthesis

  • A comparison operation (e.g. UV1 == "45")

• Any of the AND or OR operators can only be preceded by one of the following:

  • White space

  • A closing parenthesis.

• A NOT operator can only be preceded by one of the following:

  • White space

  • An opening parenthesis

  • An OR / || / | operator

  • An AND / && / & operator

• When evaluating an AND operation, if the left side of the statement evaluates to be FALSE, the right side is not evaluated. The result of this operation is of course FALSE regardless of what the result of evaluating the right side would have been.

• When evaluating an OR operation, if the left side of the statement evaluates to be TRUE, the right side is not evaluated. The result of this operation is of course TRUE regardless of what the result of evaluating the right side would have been.

Delimited Transaction Fields

TC can automatically parse your incoming transaction or request data area to extract ordered fields that are delimited by semi-colon characters. Using the delimiter characters allows you freedom from needing to maintain strict columnar alignments of your individual fields within the overall data area. You do not need to worry about having fixed-length formats for each read done by the operator, or having optional fields being skipped. As long as each field, whether filled-in or not, is delimited from the next field by a semi-colon, TC can find the correct data from the transaction or request.

The delimited fields are known in the TC scripts as TXNFIELD1 to TXNFIELD1024. Field 1 begins with the first character of the transaction or request data area, and continues up until the first semi-colon in the data area. The last field in the transaction or request must have a semi-colon separating it from the timestamp added by the DCT. Each empty field in the data must have a semi-colon delimiting it from the other fields. In short, the transaction program at the terminal should append a ";" character after each input is added to the transaction record.

  Field 1;Field 2;;Field 4 (3 was empty);...;Nth Field;

  //* Display the contents of each field
 
  //* Learn how many fields are in the txn
  Set_UV_Xact_Data( uvLOOPMAX, COUNT_TXNFIELDS, 0, 0 )
 
  UV_Math( uvLOOPCTR, =, 1 )
 
  //* Set the NEXT_TXNFIELD starting point
  //* while getting the data.
  Set_UV_Xact_Data( UV1, TXNFIELD1, 0, 0 )
 
  Do
   {
    //* Log to file as "FIELD x = field_data"
    Set_UV_Kbd_Data    ( UV2, "FIELD " )
    Append_UV_UV       ( UV2, uvLOOPCTR )
    Append_UV_Kbd_Data ( UV2, " = " )
    Append_UV_Xact_Data( UV2, UV1 )
 
    //* Don't go past end
    If ( uvLOOPMAX #> "1" )
      Set_UV_Xact_Data( UV1, NEXT_TXNFIELD, 0, 0 )
 
    UV-Math( uvLOOPCTR, +, 1 )
    UV_Math( uvLOOPMAX, -, 1 )
   }
  While ( uvLOOPMAX #> "0" )

Check_XXX Command Logic Modes

The following table describes how the commands behave for the various combinations of logic style and timeout values:

Condition	Timeout	Behavior
FOUND	0	The host screen is inspected once and the result is 'true' if the specified text or condition is present
FOUND	> 0	The host screen is inspected and the result is 'true' if the specified text or condition is present. If the text or condition is not present it delays 0.25 seconds and looks again. It repeats until either the text or condition becomes present or the maximum timeout expires. If the text or condition never appears then the result is 'false'.
NOT_FOUND	0	The host screen is inspected once and the result is 'false' if the specified text or condition is present -- or in other words the result is 'true' if the text or condition is not present.
NOT_FOUND	> 0	The host screen is inspected and the result is 'false' if the specified text or condition is present upon first inspection. If the text or condition is not present it delays 0.25 seconds and looks again. If the timeout duration expires and the specified text or condition is still not present then the result is 'true'. If the text or condition becomes present at any time up until the timeout then the result is 'false'. In other words, the command will make sure the text or condition is not there and that it does not appear for some time as it watches.
NOT_FOUND_IMMED	0	The host screen is inspected once and the result is 'false' if the specified text or condition is present -- or in other words the result is 'true' if the text or condition is not present upon first inspection.
NOT_FOUND_IMMED	> 0	The host screen is inspected and the result is 'true' if the specified text or condition is not present upon first inspection. If the text or condition is present it delays 0.25 seconds and looks again. If the timeout duration expires and the specified text or condition is still present then the result is 'false'. If the text or condition goes awy at any time up until the timeout then the result is 'true'. In other words, the command will wait for the text or condition to go away, and as soon as it is not present it will return 'true'.

Web Services

TC may be used to service requests for web services (provide), or create requests for web services (consume). For example, TC may provide other applications with access to the ERP system by exposing a web service, or may connect a data collection terminal to a remote web service.

TC provides an extension to Microsoft Windows Internet Information Server (IIS) that, with proper configuration, allows incoming HTTP requests to be routed to specific TC sessions. IIS is configured to use a TC function to handle the HTTP request if the URL includes a segment that ends with the extension ".tcws" (e.g. CreateOrder.tcws ) and the URI points to the IIS virtual directory where TC is installed (the 'TCWS' segment in the URI "http://127.0.0.1/TCWS/....")

TC can provide web services that are accessed by clients via:

• SOAP XML: The client formulates its request into an XML message that follows the SOAP schema. The TC script will be written to parse the elements of the soap:Envelope of the incoming XML and to (usually) create a response XML message in the SOAP format.

  The incoming SOAP XML message will look similar to this:

       
  <soap:Envelope>  
      <soap:Header> <!-- Optional header --> 
       [any tns:xxxx elements the sender may provide]
      </soap:Header> 
      <soap:Body>  
       [any tns:xxxx elements the sender may provide]       
      </soap:Body>         
      <HTTPRequest>
       <Method>PUT</Method>
       <ContentType>text/xml;charset="utf-8"</ContentType>
       <Accept>text/xml</Accept>
       <Host>localhost</Host>
       <SOAPAction>"http://tempuri.org/CreateOrder"</SOAPAction>
       <URI_Segment>TCWS</URI_Segment>
       <URI_Segment>CreateOrder.tcws</URI_Segment>
       <QueryString/>
      </HTTPRequest>   
  </soap:Envelope> 
              

  Note that TC adds a <HTTPRequest> element that provides easy access, via WS_GetElement, to the various HTTP header values in the incoming request. The exact set can vary based on the how the client formulates the HTTP request.

• REST URI (aka 'RESTful' or Representational State Transfer method): The request is a simple Uniform Resource Identifier, where the parameters of the request are presented in the URI segments and/or the accompanying query string. The incoming REST URI is presented to the TC web service scripting as an XML document to ease handling. The XML is in the generic format:

                 <RestRequest>
                  <Method/>
                  <[Individual elements for all header values, such as Host, User-Agent, etc.]/>
                  <URI_Segment/>
                  ... repeat occurences for each segment of the URL string
                  <QueryString>
                    <[ParmName1]>value</[ParmName1]>
                    <[ParmName2]>value</[ParmName2]>
                    ... repeat for each parameter in the query string
                  </QueryString>
                 </RestRequest>   
              

  The reponse can be a plain XML message, a JSON (Javascript Object Notation) string, or plain HTML/text.

TC can also create and send requests to web service provided by any other endpoint ('consume' web services). Again, this request can be made in either the SOAP XML format or a RESTful format, and the response can be in SOAP XML, plain XML, JSON, HTML, or plain text.

See the examples below.

Web Services Setup

Regardless of whether your TC scripts will be consuming and/or providing web services, the following steps must be done in order to define those web services for TC.

1. Create the tc2.exe.config file. You have a choice of two different methods for telling TC which web services it needs to be able to consume or provide:
   1. Using an XML file
   2. Using a database table

   TC is told of the method you have chosen via the tc2.exe.config file. This file should be created in the same directory that contains TC2.EXE (typically C:\dcconn\tc). The tc2.exe.config is used by all TC sessions.

   Below are examples of this file for each method:

   1. Using an XML file. In this case the tc2.exe.config file will use the key WSDLXMLPath to specify the full path and name of the XML file:

                  <?xml version="1.0" encoding="utf-8" ?>
                  <configuration>
                      <appSettings>
                          <add key = "WSDLXMLPath" value = "c:\wsdl.xml" />
                      </appSettings>
                  </configuration>
                  

      In the example above the XML file is C:\wsdl.xml. Below is an example of this file containing a single web service definition for the Twitter web service. Each of these parameters will be explained in the table below.

                  <?xml version="1.0" encoding="utf-8" ?>
                  <configuration>
      
                    <!-- List of Web Services -->
      
                    <!-- "TwitterXML","REST","GET","XML","","",0,0 -->
                    <WSDL>
                      <NAME>TwitterXML</NAME>
                      <WSTYPE>REST</WSTYPE>
                      <METHOD>GET</METHOD>
                      <RESPONSETYPE>XML</RESPONSETYPE>
                      <TARGETNAMESPACE></TARGETNAMESPACE>
                      <SOAPACTION></SOAPACTION>
                      <PORT>0</PORT>
                      <TWCS_RESPONSE_SECS_MAX>0</TWCS_RESPONSE_SECS_MAX>
                    </WSDL>
      
                  </configuration>
                  

      If you have multiple web services to define, then the <WSDL> section should be repeated for each of those web services.

   2. Using a database table. In this case the tc2.exe.config file will use the keys connectionString, schema and table to specify the database and table that contains the web service definitions. Set the data source name (dsn) per the Windows ODBC data source you have already created. Note that if you saved the password with the Windows data source you can remove the uid and pwd pieces of information from the config file. Set the database schema and table name as appropriate.

                  <?xml version="1.0" encoding="utf-8" ?>
                  <configuration>
                      <appSettings>
                  	    <add key = "connectionString" value = "dsn=oDCLIBdb2;uid=myuser;pwd=mypw;"/>
                          <add key = "schema" value = "DCLIB"/>
                  	    <add key = "table" value = "WSDL"/>
                      </appSettings>
                  </configuration>
                  

2. Create the database table or .XML file and populate them with the parameters for each Web Service.

   If using a database table, you will have one record per web service in that table. If using the XML file, you will have one <WSDL> section in that XML file for each web service. The set of parameters are named the same in either case.

   The first column in the table below is the parameter name in the XML file if you are using that method. But it is the database column name in your table if you are using that method. The second column in the table below specifies the data type and applies only if you are using a database table. The last column in the table below describes the parameter usage, regardless of whether it came from an XML file or database table:

   XML parameter / database column Name	Data Type	Description of Use
   Name	VARCHAR(25) Primary Key	Name of the web service. In the incoming web service request, this is the "filename" in front of the ".tcws" extension in a segment of the URL. In this RESTful request, "http://127.0.0.1/TCWS/TestRest.tcws/testing.xml?x=ThisIsXValue&y=8.12&zzzzz=ZZZZZ", the name would be "TestRest" (case sensitive). Or in this SOAP request, "http://localhost/TCWS/CreateOrder.tcws", the name would be "CreateOrder"
   WSType	VARCHAR(25)	For a web service that is provided by TC, this is the expected type of incoming request for the web service name. For a web service request created by TC (i.e. WS_CreateRequest) this is the request type expected by the provider. This may be one of the values "SOAP" or "REST" -- no other types are supported.
   Method	VARCHAR(12)	The HTTP Request Method to use in a web service request created by TC (only used in WS_CreateRequest / WS_SendRequest). This can be be "GET", "PUT", "POST", "DELETE" or "OPTION". For SOAP requests this is generally 'GET'. For REST requests the method is often used as a verb with specified meaning per the particular web service (with PUT/POST/DELETE often for requests that affect data on the server, and 'GET' for inquries that leave no effect
   ResponseType	VARCHAR(12)	To specify what type is response is expected by TC when it sends a request, or what type of response it should formulate when replying to a reqeust. This can be SOAPXML (XML with the specific SOAP schema), XML, JSON (Javascript Object Notation), HTML, or TEXT.
   TargetNamespace	VARCHAR(128)	Specifies the "tns" namespace for incoming and outgoing XML messages. Use of this data element is optional. For namespaces, use of the WS_DefineNamespace and/or WS_AddAttribute commands is advised because of the increased flexibility and clarity. This can be used for SOAP messages and is taken from the WSDL (Web Services Definition Language) file provided by the web service provider. Search in the WSDL XML file for 'targetNamespace="http://something.something/"' and copy the 'http://..../' URL (including trailing slash) to this column of the table. This namespace is used to give meaning to the "tns:" prefix that TC uses to give namespace meaning to the application-specific fields in a SOAP message that it creates, and is used to give meaning to whatever default namespace prefix is used on SOAP messages that arrive from outside of TC. For parsing of simple XML responses that come back to TC from other web service provides, this column may be set to an empty string (''). For simple XML responses created by TC, set this to any unique 'http://..../' URL (it does not need to actually exist) and refer to it in WS_CreateElement / WS_SetElement commands using the standard "tns:" prefix.
   SOAPAction	VARCHAR(128)	This is the SOAPAction that is included in the header of outgoing SOAP web service requests that are created by TC. This is needed only for SOAP message request creation. Get the value from the SOAP WSDL document provided by the web service. Search for the SOAPAction that represents the desired web service operation in the SOAP format (e.g. look for '<soap:operation' and copy the soapAction value, such as soapAction="http://tempuri.org/ShowOrder")
   PORT	INTEGER	This is the local port number to use in communications between the IIS web server and TC. The value is used only for web services PROVIDED by the local TC sessions(s) and must be a unique integer for each of those services (use a number not in use for any other service on the computer). For web service names that are only called from TC sessions you can use any value and they do not need to be unique amount rows in the table (so, 0 is suggested).
   TWCS_Response_Secs_Max	INTEGER	Set to how many seconds the Local IIS web server should allow for a response to be returned from the TC session that serves a web service name. This is not used when TC calls a remote web service.

   If you are creating a database table, the SQL to create this table is similar to:

   CREATE TABLE "DCLIB.WSDL"  ( NAME VARCHAR(25) NOT NULL , WSType VARCHAR(25), Method VARCHAR(12), ResponseType VARCHAR (12), TargetNamespace VARCHAR(128) , SOAPAction VARCHAR(128),
   PORT integer, twcs_response_secs_max integer, PRIMARY KEY (NAME) ) 
   

If TC will be providing web services, then two additional steps must be performed:

1. Create web.config to inform all web service "provider" TC sessions where to get information about the web service each will handle - in the same way that tc2.exe.config is used for "consumer" TC sessions. Adjust the dsn, schema, and table as was done for the tc2.exe.config file above. Likewise, the WSDLXMLPath keyword can be used instead of the database parameters.

   web.config should be created in the same directory that contains TC2.EXE and tc2.exe.config (typically C:\dcconn\tc). Here is a sample web.config file:

               <?xml version="1.0" encoding="utf-8" ?>
               <configuration>
                 <appSettings>
               	<add key = "connectionString" value = "dsn=oDCLIBdb2;uid=myuser;pwd=mypw;"/>
               	<add key = "schema" value = "DCLIB"/>
               	<add key = "table" value = "WSDL"/>
                 </appSettings>
               </configuration>
               

   Note: Previous versions of these instructions included a <system.webServer> and <handlers> element in the web.config contents above. Instead the handler definition is now set up in the IIS configuration steps below.

2. Configure IIS. Microsoft Internet Information Services must be configured to be able to use TC's WebServiceHandler.dll to handle incoming requests for web services.
   1. If you do not already have an Application Pool that is set to use .NET Framework v2.0.50727 and 'Integrated' managed pipeline mode then add a new pool with these attributes (Basic Settings) and call it something like 'DCC32'. This application pool must also be set to allow 32-bit applications (Advanced Settings, General section). And, if it is not already set, make sure the Identity is set to LocalSystem in the Process Model section, also in Advanced Settings.

      Note: While 'Integrated' is the recommended request-processing mode, 'Classic' mode can work as well.

   2. Create a new web site and set its name to DCCpp, for example, where 'pp' is the port number that you will use. For this example, we'll use port 88 and so the web site will be called DCC88.

      Set the physical path to the default which is typically c:\inetpub\wwwroot and set the port to 88 or to whatever number you have chosen.

      Also set the application pool to DCC32 or whatever one you have that has been created with the settings described in the previous step.

      Finally, set up the connection user ID and password as needed.

   3. Create a new virtual directory under the web site that you created in the previous step. Name the virtual directory something like 'TCWS' and point it to the C:\DCCONN\TC directory (or wherever your Transaction Connection is installed). The virtual directory name you choose (e.g. TCWS) will become part of the URI / endpoint for the web services provided by TC. For example:
      • http://127.0.0.1:88/TCWS/ValidateUser.tcws?userid=JohnDoe&pw=4d103f3e229402f325ea12784c42198d

   4. IIS needs to be told that TC's WebServicesHandler.dll is the handler for all URLs with a ".tcws" extension. For example:
      • http://127.0.0.1:88/TCWS/ValidateUser.tcws?userid=JohnDoe&pw=4d103f3e229402f325ea12784c42198d

      For the same web site created above, use the Handler Mappings option in the IIS section to Add a Managed Handler with the following initial parameters:

      • Request path: *.tcws
      • Type: WebServiceHandler.clsIISExtension
      • Name: TC web service

      And the following Request Restrictions:

      • Mapping: uncheck “Invoke handler only if …”
      • Verbs: select All verbs
      • Access: Script

      IIS stores the above settings in a file called web.config but it is in the c:\inetpub\wwwroot folder. The contents of that folder will look something like:

              <?xml version="1.0" encoding="utf-8" ?>
              <configuration>
                 <system.webServer>
                    <handlers>
                       <add verb="*" path="*.tcws" type="WebServiceHandler.clsIISExtension" resourceType="Unspecified"/>
                    </handlers>
                 </system.webServer>
              </configuration>
              

      Note: In previous versions of these instructions, the above <handlers> definition was included in the web.config that was created in the c:\dcconn\tc folder. In fact, that <handlers> definition could be in either web.config (but not both) and things would work. But only the one in the c:\inetpub\wwwroot folder is managed by the IIS user interface that is used for configuring handlers and other web service settings.

   5. Register the DLL: The installation of TC should have automatically taken care of this step. However, if you get an error popup from TC when your script is attempting to execute a web service-related command (e.g. WS_CreateRequest, WS_CreateResponse) then you may need to register this .DLL manually:

      From the directory where TC's WebServiceHandler.dll resides (e.g. C:\DCCONN\TC\BIN) run the .bat file:

       regtcweb.bat
                  

      This .bat file performs the following commands for you.

       %SystemRoot%\Microsoft.NET\Framework\v2.0.50727\regasm.exe /unregister /tlb WebServiceHandler.dll
       %SystemRoot%\Microsoft.NET\Framework\v2.0.50727\regasm.exe /tlb WebServiceHandler.dll
       %SystemRoot%\Microsoft.NET\Framework\v2.0.50727\regasm.exe /codebase WebServiceHandler.dll
                  

      Note that on the last command you may get a warning about registering an unsigned assembly and strong naming; this can be ignored.

      Also note that if you ever get an update to the TC program, which is usually provided as a .zip file to update the c:\dcconn\tc directory, then the regtcweb.bat file needs to be rerun after installing that TC update, so that the new version of the WebServiceHandler.dll is registered.

   6. Make sure you have created the web.config file described in step 1 above and then stop and restart the IIS web site that you created (e.g. DCC88)

   7. Now that the web site is restarted, the web.config file should have been read which in turn should have registered the *.tcws extension. Verify this by selecting the Virtual Directory that you added above (e.g. TCWS) and then looking at the Handler Mappings for the path *.tcws. It should have the following parameters:
      • Executable: C:\Windows\Microsoft.NET\Framework\v2.0.50727\aspnet_isapi.dll
      • Name: Transaction Connection
      • Verbs: All verbs
      • Access: Execute

   8. The WebServiceHandler.dll may also need to be copied to other locations in order for IIS to find it. If IIS cannot find this .DLL there will likely be an entry in the Windows Event Viewer, in the Application section of the Windows Logs when an attempt is made to call any TC provider web service. Try any of the following locations (but always keep it wherever TC is installed no matter where it is copied):
      • c:\inetpub\wwwroot\bin
      • c:\inetpub\wwwroot
      • c:\dcconn\tc\bin (or .\bin under wherever TC is installed)

Web Service Examples

• Call a SOAP Web Service
• Provide a SOAP Web Service
• Call a RESTful Web Service
• Provide a RESTful Web Service

Call a SOAP Web Service

Sub CallWS()

   // Form this SOAP request to obtain the stock price for IBM:
   //  <soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance/" xmlns:xsd="http://www.w3.org/2001/XMLSchema/" 
   //    xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:qns="http://www.xignite.com/services/">
   //  <soap:Header>
   //     <qns:Header>
   //        <qns:Username>hornern@us.ibm.com</qns:Username>
   //        <qns:Password>Fred</qns:Password>
   //        <qns:Tracer>?</qns:Tracer>
   //     </qns:Header>
   //  </soap:Header>
   //  <soap:Body>
   //     <qns:GetGlobalDelayedQuote>
   //        <qns:Identifier>IBM</qns:Identifier>
   //        <qns:IdentifierType>Symbol</qns:IdentifierType>
   //     </qns:GetGlobalDelayedQuote>
   //  </soap:Body>
   //  </soap:Envelope>

   Declare (handle)
   Declare (rc)
   Declare (RespHandle)
   Declare (outValue)
   Declare ( CurrTS )
   
   Set_UV_Data_Part( CurrTS, CURRENT_TIMESTAMP, 0, 0 ) 

   Declare( WSName )
   Set_UV_Kbd_Data( WSName, "Quote" )
   
   // Initialize a SOAP XML document with the targetNamespace found in the local 
   // web services table under  name 'Quote'.  
   // This will form the shell of the SOAP XML as shown below and associate 
   // with the handle returned in 'handle' UV.
   // 'The Name Space' qns: is set to the targetNamespace
   //  <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" ...xmlns
   //     :qns="http://www.xignite.com/services/">
   //  <soap:Header>
   //  </soap:Header>
   //  <soap:Body>
   //  </soap:Body>
   //  </soap:Envelope>
   WS_CreateRequest(handle,WSName, rc)
                        

   // At this point our WS XML navigation is pointed at the soap:Envelope node.  
   
   // Add a custom namespace attribute to the soap_Envelope using the special prefix "xmlns:" 
   WS_AddAttribute( handle, "xmlns:qns", "http://www.xignite.com/services/", rc ) 
                        
   // Put qns:Header section in soap:Header and populate with userid, password    
   
   // Navigate to soap:Header as the current node             
   WS_EnterElement(handle,"soap:Header", 1, rc) 
   
   // Create qns:Header inside of soap:Header
   WS_CreateElement(handle, "qns:Header", rc)      
   
   // Make qns:Header the current node
   WS_EnterElement( handle, "qns:Header", rc )
   
   If( rc #<> 0 )
     Log_Error("Did not create/enter qns:Header!", ERROR ) 
   
   // Inside of qns:Header create and populate 3 nodes
   WS_SetElement( handle, "qns:Username", 1, "hornern@us.ibm.com", rc )     
   WS_SetElement( handle, "qns:Password", 1, "Frred", rc )     
   WS_SetElement( handle, "qns:Tracer", 1, "myTracer", rc )     
      
   WS_LeaveElement( handle, rc ) //  Backup one to soap:Header                                                                       
   WS_LeaveElement( handle, rc ) //  Backup one to soap:Envelope 
   
   // Done building Header 
   
   // Make soap:Body the current node
   WS_EnterElement(handle,"soap:Body", 1, rc)  // Enter soap:Body, hopefully
   
   // Create node and make it current
   WS_CreateElement(handle,"qns:GetGlobalDelayedQuote", rc)  
   WS_EnterElement(handle,"qns:GetGlobalDelayedQuote", 1, rc)

   // Create and then set Identifier 
   // (Note: Could be done simply with WS_SetElement as above)
   WS_CreateElement(handle,"qns:Identifier", rc)
   // WS_SetElement (handle, param name, [occurrence, ] field value, return code)
   WS_SetElement    (handle, "qns:Identifier",   1,           "IBM",       rc)
   
   // Create and set Identifier type
   WS_CreateElement(handle,"qns:IdentifierType", rc)
   WS_SetElement(handle,"qns:IdentifierType",1,"Symbol", rc)    
   
   // Log the SOAP XML doc we are about to send 
   WS_ToFile( handle, "%TC2%\soaprequest.xml", rc ) 
	
   // Send the web service request, waiting up to 30 seconds for response
   // 	
   WS_SendRequest(handle, "http://www.xignite.com/xGlobalQuotes.asmx", rc, RespHandle, 30 )        
   
   If( rc #== 0 )
   { 
       // Tell the parser we will find the reply elements of namespace "http://www.xignite.com/services/" 
       // via our chosen prefix 'rqns':  
       WS_DefineNamespace( RespHandle, "http://www.xignite.com/services/", "rqns", rc )   
       
       // Log the SOAP XML response we received
       WS_ToFile( RespHandle, "%TC2%\soapresponse.xml", rc ) 
       
       // Navigate into result part of response XML  
       
       // Note:  Already positioned at soap:Envelope node, so this will fail harmlessly
       WS_EnterElement( RespHandle, "soap:Envelope", rc )  
       
       // Navigate into soap:Body and then into ...Response and ...Result sections
       WS_EnterElement( RespHandle, "soap:Body", rc )
       WS_EnterElement( RespHandle, "rqns:GetGlobalDelayedQuoteResponse", rc ) 
       WS_EnterElement( RespHandle, "rqns:GetGlobalDelayedQuoteResult", rc ) 
        
       // Get the rqns:Last price 
       WS_GetElement (RespHandle, "rqns:Last", 1, outValue, rc)
       
       Log_Error( "Success!", INFO ) 
       Log_Error( outValue, INFO ) 
   }
   Else
   {
       Log_Error( "Failed to get response", ERROR )
   }
   
   // Must destroy handles so they can be re-used.  Failure to destroy will 
   // 'leak' handles and eventually run out / stop working.
   WS_Cleanup (handle)
   WS_Cleanup (RespHandle)
   


EndSub()

Provide a SOAP Web Service

Start_WS ("CreateOrder", gHandle)

   Declare (varA)
   Declare (varB)
   Declare (outHandle)
   Declare (rc)
   Declare ( OrderID )
   Declare ( OrderDate )
   Declare ( Qty)
   Declare ( Price ) 
   Declare ( ItemID ) 
   Declare ( ItemName ) 
   Declare ( OrderLineID)
   Declare ( CurrTS )
   Declare ( Method ) 
   Declare ( RequestHost ) 
   
   Log_Error( "Processing CreateOrder ", INFO ) 
   
   Set_UV_Data_Part( CurrTS, CURRENT_TIMESTAMP, 0, 0 ) 
   
   // Upon start-up of this scriptlet, the incoming SOAP XML
   // has been stored under the handle saved in gHandle.  The current
   // node is automatically set to the soap:Envelope node, so we can
   // navigate directly into the HTTPRequest element:
   
  
   WS_EnterElement( gHandle, "HTTPRequest", 1, rc )  
   WS_GetElement( gHandle, "Method", Method, rc ) 
   WS_GetElement( gHandle, "Host", RequestHost, rc ) 
   
   if( Method <> "POST" )
   {
       // Do something else, like return FAULT message and lot
       // bad request from the RequestHost
   }
   
   WS_LeaveElement( gHandle ) // Return to soap:Envelope node
   
   WS_EnterElement(gHandle,"soap:Body", 1, rc)
   
   // Navigate into the default namespace's CreateOrder section.
   WS_EnterElement(gHandle,"tns:CreateOrder", 1, rc)

   // Get some values that are in the 'tns:' default namespace
   WS_GetElement (gHandle, "tns:orderID", OrderID, rc)
   WS_GetElement (gHandle, "tns:orderDate", OrderDate, rc)
   WS_GetElement (gHandle, "tns:orderLineID", OrderLineID, rc)
   WS_GetElement (gHandle, "tns:qty", Qty, rc)
   WS_GetElement (gHandle, "tns:price", Price, rc)
   WS_GetElement (gHandle, "tns:itemID", ItemID, rc)
   WS_GetElement (gHandle, "tns:itemName", ItemName, rc ) 
   
   // Create a reponse message, referenced by outHandle.
   // Based on ResponseType in the web services table, this creates
   // a SOAP XML message with empty soap:Header and soap:Body elements.
   WS_CreateResponse (gHandle, outHandle)
   
   // Enter the soap:Body and create a hierarchy of sections
   // tns:CreateOrderResponse and its child tns:CreateOrderResult
   WS_EnterElement( outHandle, "soap:Body", 1, rc )

   WS_CreateElement(OutHandle,"tns:CreateOrderResponse", rc);
   WS_EnterElement( outHandle, "tns:CreateOrderResponse", rc ); 
   
   WS_CreateElement(OutHandle,"tns:CreateOrderResult", rc)
   WS_EnterElement( outHandle, "tns:CreateOrderResult", rc ); 
   
   // Create then set a value
   WS_CreateElement(OutHandle,"tns:orderID", rc)
   WS_SetElement (outHandle,"tns:orderID",1, OrderID, rc)
   
   // Create AND set a value in one step
   WS_SetElement (outHandle,"tns:price",1, Price, rc)
   
   // Retreat back to tns:CreateOrderResponse 
   WS_LeaveElement( outHandle, rc )
   
   // Create and set tns:Trash is tns:CreateOrderResponse 
   WS_SetElement (outHandle,"tns:Trash",1, CurrTs, rc)

   // Send our response and clean-up
   WS_SendResponse (outHandle)

   WS_Cleanup (outHandle)
   WS_Cleanup (gHandle)
   
   // All done serving this request
   
End_WS ()

Call a RESTful Web Service

Sub CallTwitter()

   Declare (handle)
   Declare (rc)
   Declare (RespHandle)
   Declare (outValue)
   Declare ( CurrTS )
   Declare ( URL ) 
   Declare ( Timeout )
   Declare ( Occur )
   Declare ( Sect ) 
   
   Set_UV_Data_Part( CurrTS, CURRENT_TIMESTAMP, 0, 0 ) 

   WS_CreateRequest(handle,"TwitterXML", rc)
 
   UV_Math( Timeout, =, 4, 0.0 )
   
   // Ask for statuses for user NealHorner.  
   // The URI segment 'user_timeline.xml' tells Twitter we want an 
   // XML document as a response (we could change to .JSON to get JSON style)
   Set_UV_Kbd_Data( URL,  "http://twitter.com/statuses/user_timeline.xml?id=NealHorner" )   
   
   // Send the request and get the response in handle RespHandle.
   // Any error message can be returned in glLarge2 user variable. 
   WS_SendRequest(handle, URL, rc, RespHandle, Timeout, glLarge2 )   
   
   If( rc #== 0 )
   {   
       // Enter the 2nd occurrence of the status element in the response
       UV_Math( Occur, =, 2 );
       Set_UV_Kbd_Data( Sect, "status" );
       WS_EnterElement( RespHandle, Sect, 2, rc ) 
      
       // Get some values
       WS_GetElement (RespHandle, "text", 1, glLarge2, rc) 
       Log_Error( glLarge2, INFO ) 
      
       WS_GetElement (RespHandle, "user", 1, glLarge2, rc) 
       Log_Error( glLarge2, INFO ) 
       
       WS_EnterElement( RespHandle, "user", 1, rc )
       
       UV_Math( Occur, =, 1 )
       WS_GetElement (RespHandle, "name", Occur , glLarge2, rc) 
       Log_Error( glLarge2, INFO ) 
      
   }
   
   WS_Cleanup (handle)
   WS_Cleanup (RespHandle)

EndSub()

Provide a RESTful Web Service

To test this web service, run this from a browser:
http://127.0.0.1/TCWS/TestRestX.tcws/testing.xml?x=ThisIsXValue&y=8.12&zzzzz=ThisIsZValue

Note that some segement of the URI must contain the text extension ".tcws" so that IIS can route the reqeust to Transaction Connection. The ".tcws" extension can be in any segment (so this will also work:
http://127.0.0.1/TCWS/AnotherSegment/TestRestX.tcws/testing.xml?x=ThisIsXValue&y=8.12&zzzzz=ThisIsZValue

// Catch REST request and respond with XML 
// To Test, use this in browser address bar: http://127.0.0.1/TCWS/TestRestX.tcws/testing.xml?x=ThisIsXValue&y=8.12&zzzzz=ThisIsZValue
Start_WS ( "TestRestX", gHandle)

   Declare( RespHandle )
   Declare( rc ) 
   Declare( Method )
   Declare( Seg )       
   Declare( Value )
   Declare( XValue ) 
   Declare( RespHTML )
   Declare( TestResult )  
   Declare( CurrTS )
   
   Set_UV_Data_Part( CurrTS, CURRENT_TIMESTAMP, 0, 0 )  
   
   // Note that an incoming REST request is automatically parsed by TC
   // into an XML document that looks like this, and the current node
   // is set to the RestRequest element.
   // <RestRequest>
   //  <Method>GET</Method>
   //  <Host>127.0.0.1</Host>
   //  <User-Agent>Mozilla/5.0...</User-Agent>
   //  ... other header values ...
   //  <URI_Segment>TCWS</URI_Segment>
   //  <URI_Segment>TestRestX.tcws</URI_Segment> 
   //  <URI_Segment>testing.xml</URI_Segment>        
   //  <QueryString>
   //    <x>ThisIsXValue</x>
   //    <y>8.12</y>
   //    <zzzzz>ThisIsZValue</zzzzz>
   //  </QueryString>
   // </RestRequest>   
   
   // Obtain the incoming Method used by the web service caller.
   // This might be used to decide what kind of action to take.
   WS_GetElement ( gHandle, "Method", Method, rc )   
  
   // Get each URI_Segment value in turn.  There are only
   // 3, so the 4th try will return -1.                                                
   WS_GetElement ( gHandle, "URI_Segment", 1, Seg, rc )   
    
   WS_GetElement ( gHandle, "URI_Segment", 2, Seg, rc )   
       
   WS_GetElement ( gHandle, "URI_Segment", 3, Seg, rc )  
   WS_GetElement ( gHandle, "URI_Segment", 4, Seg, rc )     
   
   // Navigate into the QueryString area
   WS_EnterElement ( gHandle, "QueryString", rc )     
    
      // Obtain each of the expected query string values
      WS_GetElement ( gHandle, "x", XValue, rc )  
        
      WS_GetElement ( gHandle, "y", 1, Value, rc )  
       
      WS_GetElement ( gHandle, "zzzzz", 1, Value, rc )    
      
   WS_LeaveElement( gHandle )            
    
   // Create a response to the request.  Because the ResponseType is 
   // set to 'XML' this creates an empty XML document
   WS_CreateResponse( gHandle, RespHandle ) 
   
   // This creates the first element in the XML response and sets
   // the current node to this element.  
   // Note that the response is formulated around the default 
   // namespace "tns:" (that resolves to http://ibmdc.com/ per the
   // web services table)
   WS_CreateElement ( RespHandle, "tns:Answer", rc )
  
      // Create an element 
      WS_CreateElement( RespHandle, "tns:XvalueIs", rc )
      
      // Set that element
      WS_SetElement( RespHandle, "tns:XvalueIs", 1, XValue, rc )
       
      // Create and set some elements:
      WS_SetElement( RespHandle, "tns:XvalueIs", 2, "AnotherX", rc )
        
      WS_SetElement( RespHandle, "tns:XvalueIs", 3, CurrTS, rc )
       
   WS_LeaveElement( RespHandle )
   
   // Send the response
   WS_SendResponse( RespHandle )
   
   WS_Cleanup ( gHandle )
   WS_Cleanup ( RespHandle )
   
End_WS()

• HTML Document

  Change the ResponseType in the web services table to "HTML" and change the response formation/sending part of the script to be something like:

          Begin_UV()
             <html><body><h1>Here is your response</H1>Xvalue is :XValue(X)</body></html>
          End_UV( RespHTML )
     
          WS_SendResponse( RespHandle, RespHTML )
          

• JSON Document

  Change the ResponseType in the web services table to "JSON" and change the response formation/sending part of the script to be:

             Begin_UV()
               [{answer:"yes",someobj:{x::XValue(X),y:14}, more:12.3}]
             End_UV( RespJSON )
     
             WS_SendResponse( RespHandle, RespJSON )
          

Logon and Logoff Scripts

After connecting to the host session, or connecting to the database, TC will run the StartLogon script, if it is defined. This gives you an opportunity to initialize user variables or perform other operations that must be done before any transactions/requests are processed.

Likewise, before TC shuts down or terminates the host or database connection, it will run the StartLogff script, if it is defined.

The following is how Logon and Logoff commands blocks can be organized.

  StartLogon ()
  EndLogon ()
 
  StartLogoff ()
  EndLogoff ()
 
  StartKey( F1 )
  EndKey()

SQL Statement Generation

TC has commands that allow you to create general INSERT, UPDATE, and SELECT SQL statements with properly formatted data from your transactions. You do not need to know much about SQL and databases to be up and running with your application. The following sections describe how these SQL statements are created by the commands, and shows the form of the SQL statement.

When you find the need for a more flexible method of creating the SQL statement, you can use the free-form SQL input method, described in Free-Form SQL Statements. The formats shown for the insert, update, and select statements created from commands are a useful quick-reference for creating these types of statements with free-form SQL.

Insert Statement

TC uses the commands Insert_DB_Table, Setup_Insert_Field, and Perform_Insert to create a general INSERT statement of the form:

  INSERT INTO QUALIFIER.TABLENAME                         (1)
    (COLUMN_NAME_1, COLUMN_NAME_2,..., COLUMN_NAME_N)     (2)
  VALUES                                                  (3)
    (VALUE_1, VALUE_2,..., VALUE_N)                       (4)

The command Insert_DB_Table creates line 1 of the statement, while command Setup_Insert_Field creates lines 2, 3, and 4. Setup_Insert_Field can be called multiple times to set up as many as 255 column names with associated values. The values may be constants, data from parts of the transaction, data from user variables, or database special registers (for example, CURRENT TIME, CURRENT DATE, and so forth). Perform_Insert terminates the list of column names and values and causes the SQL statement to be performed.

See Inserting a Record into a Table for an example of using these commands.

Update Statement

The commands Update_DB_Table, Setup_Update_Field, Update_Where, and Perform_Update are used to create a general UPDATE statement of the form:

  UPDATE QUALIFIER.TABLENAME                             (1)
    SET COLUMN_NAME_1 = VALUE_1                          (2)
    SET COLUMN_NAME_2 = VALUE_2                          (3)
    SET COLUMN_NAME_N = VALUE_N                          (N)
  WHERE COLUMN_NAME_X comparison VALUE_X                 (N+1)

The command Update_DB_Table creates line 1 of the statement, while command Setup_Update_Field creates lines 2, 3, and to line N. Setup_Update_Field can be called multiple times to set up as many as 255 column names with associated values. The values can be constants, data from parts of the transaction, data from user variables, data from another column in the row, or database special registers (for example, CURRENT TIME, CURRENT DATE, and so forth). Update_Where creates the last line (N+1), which specifies the row conditions where the columns should be updated. Perform_Update causes the SQL statement to be performed.

See Updating a Record in a Table for an example of using these commands.

Select Statement

The commands Select_From_DB_Table, Select_Column, Select_Where, Select_Having, Select_Group_By, Select_Order_By, and Perform_Select create a general SELECT statement of the form:

  SELECT COLUMN_1, COLUMN_2,... COLUMN_N           (1)
    FROM QUALIFIER.TABLENAME                       (2)
    [WHERE COLUMN_X comparison VALUE_X]            (3)
    [GROUP BY COLUMN_Y]                            (4)
    [HAVING COLUMN_Z comparison VALUE_Z]           (5)
    [ORDER BY COLUMN_W]                            (6)

The command Select_From_DB_Table creates line 2 of the statement, while command Select_Column creates line 1. Select_Column can be called multiple times to set up as many as 255 column names or column operations (for example, SUM, MAX, and so forth). Select_Where creates line 3, which specifies the row conditions where the columns should be selected. Select_Group_By, Select_Having, and Select_Order_By create lines 4, 5, and 6, respectively. All lines in brackets ([]) are optional.

The values can be constants, data from parts of the transaction, data from user variables, or database special registers (for example, CURRENT TIME, CURRENT DATE, and so forth)

Perform_Select causes the SQL statement to be performed.

See Querying the Database Table for an example of using these commands.

Free-Form SQL Statements

You can create and execute any valid SQL statement that can be dynamically performed. If using IBM DB2, refer to the online SQL Reference for guidance on SQL statements and on which commands can and cannot be performed dynamically. If using ODBC to connect to other database types, refer to the documentation provided with the database software. Those commands that cannot be performed dynamically are generally provided for by TC commands such as Commit_Changes and Perform_Fetch.

Using free-form SQL statements is required when any of the following conditions are true:

• Your desired SQL Insert, Update, or Select statement cannot be accomplished using the facilities of the high-level commands provided for these functions. This would generally happen if some esoteric functions were required.

• Your WHERE statement in an Update or Select statement must refer to two or more different areas of the transaction or other data area. The high-level commands for specifying the Where condition are limited to dealing with a single user variable or part of the transaction.

• You are an experienced SQL user and simply prefer the ease of using the free-form style (but you would rather not write a complete C program to do this work).

A free-form SQL statement begins with the command Begin_SQL / Begin_SQL2 / Begin_Select / Begin_Select2 and ends with a End_SQL / End_SQL2 / End_Select / End_Select2. Between the begin and end SQL commands, you can place the text of the SQL statement. You can compose the SQL statement using new lines and blank lines as you desire for readability. TC will concatenate all the data into one long string, discarding extraneous leading and trailing spaces and blank lines.

You cannot have any other TC commands within the begin / end SQL commands. Comments may be included, as long as the entire line is considered a comment; comments at the end of a line containing SQL are considered part of the SQL.

Note:

See Limit on SQL Statement Size for important information on the size limitation on your SQL statement.

Only one SQL statement can be enclosed in a Begin_SQL / End_SQL pair (or similar commands). For example, an UPDATE and a INSERT must be separated into 2 free-form SQL sections.

Using User Variables and Transaction Fields in SQL Statements

Your TC scripts will often include SQL statements which will need to change each time the script is run. For example, in a warehouse application, a script may be set up to find out which stock locations contain a certain part number with at least X parts in that location. The part number and quantity desired comes from data in the transaction from the terminal operator.

TC provides a mechanism to do on-the-fly substitution for parts of the SQL statement with data from TC user variables or transaction fields. The SQL statement can include references to user variables by putting the user variable name (or UVn format) directly into the SQL, preceded by a colon. Similarly, you can include references to transaction fields such as TXNFIELD1, TXNFIELD2, ... directly in the SQL, preceded by a colon.

The following example shows how user variables references might be included in the SQL statement:

  // Get the part number string from the transaction
  Append_UV_Xact_Data( UV1, TXNFIELD1, 0,  0 )
  Format_UV( UV1, CHARACTER )
 
  // Get the quantity string from the transaction
  Append_UV_Xact_Data( UV2, TXNFIELD2, 0, 0 )
  Format_UV( UV2, NUMERIC )
 
  Begin_SQL()
 
    SELECT PART_NUMBER, QUANTITY, LOCATION
    FROM MFG.WAREHOUSE
    WHERE PART_NUMBER=:UV1 AND QUANTITY>=:UV2
 
  End_SQL()

When the script is compiled, TC keeps track of all references to user variables and transaction fields. At execution time, these references are replaced by the actual contents of the user variables/transaction fields, producing the actual SQL statement that will be performed.

In the example above, the command Format_UV is used to format the user variables prior to use in the SQL statement because the database requires numeric, character, and time/date values to be in distinct, specific formats.

To make this easier, TC allows the use of 'format specifiers' immediately following user variable/transaction field reference, enclosed in parentheses. The specifier may be one of :

  (C) for CHARACTER
  (N) for NUMERIC
  (T) for TIME
  (D) for DATE
  (S) for TIMESTAMP
  (X) for no formatting
 

Here are some examples:

  :UV10(C)
  :MyUserVar(T)
  :TXNFIELD27(N)

The formatting works as described under command Format_UV, except that the user variable or transaction field data is not directly modified, only the copy of the data placed in the free-form SQL statement is modified.

Using these TC features, the example above can be simplified:

  Begin_SQL()
 
    SELECT PART_NUMBER, QUANTITY, LOCATION
    FROM MFG.WAREHOUSE
    WHERE PART_NUMBER=:TXNFIELD1(C) AND QUANTITY>=:TXNFIELD2(N)
 
  End_SQL()

The epitome of user variable/transaction field substitution in your free-form SQL would be to fully compose the SQL statement at the data collection terminal and create it as a single transaction field:

  // Get the SQL statement from the transaction
  Begin_SQL()
 
    :TXNFIELD1
 
  End_SQL()

:sqlCurrentTime Macro

There is another kind of substitution that TC can do when your SQL statements have to work with more than one database type. TC provides special macros for certain database functions so that it can do substitution for those macros, based on the current database type, when it prepares the SQL statement.

Today there is only one macro like this and it is used for the SQL function that returns the current date and time. This macro, :sqlCurrentTime, can be used in the free-form SQL statement and TC will substitute the appropriate SQL function name based on the database type currently in use. For example, the following SQL works only with DB2:

  Begin_SQL ( )
 
    UPDATE DCERP.LP_INFO
    SET    Locn = :uvtLOCN_TO(C),
           Last_Txn = :uvtTXN_TYPE(C),
           Update_Timestamp = CURRENT TIMESTAMP
    WHERE LP#    = :uvtLP#(C) and
           Branch = :uvgBranch(C)
 
  End_SQL ( Unexpected_Database_Error )

But if we substitute the macro :sqlCurrentTime for CURRENT TIMESTAMP, TC will be able to do the appropriate substitution for this macro to generate SQL that is valid for other database types such as Oracle and SQL Server:

  Begin_SQL ( )
 
    UPDATE DCERP.LP_INFO
    SET    Locn = :uvtLOCN_TO(C),
           Last_Txn = :uvtTXN_TYPE(C),
           Update_Timestamp = :sqlCurrentTime
    WHERE LP#    = :uvtLP#(C) and
          Branch = :uvgBranch(C)
 
  End_SQL ( Unexpected_Database_Error )

TC knows what function name should be substituted based on the value of the keyword CURRENT_TIME_FUNCTION for the current database type definition in the DBTYPE.INI file. For more information about DBTYPE.INI and the keyword CURRENT_TIME_FUNCTION please see DBTYPE.INI.

SQL Statement Lifetimes

    //Fill a packing list table with the part numbers,
    //quantities and item descriptions of everything
    //of record which has been loaded onto a pallet
 
    Begin_SQL()
 
      SELECT  A.ITEM, QUANTITY, DESCRIPTION
        FROM PALLETS A, ITEMS B
      WHERE PALLET_NUMBER=:uvtPallet(N)
      AND A.ITEM = B.ITEM
 
    End_SQL()
 
    //* Clear uvSQLRC and set SQL 100 vector to
    //* point to a routine which will set uvSQLRC
    //* with text "NO ROWS"
    CallSubroutine( PrepForSQL100 )
 
  Get_More:
 
    Perform_Fetch()
 
    //* If we got no SQL 100 error...
   If ( uvSQLRC == "" )
    {
     //* Got a row
     Set_UV_Select_Data( uvs1, 1 )   //* Item
     Set_UV_Select_Data( uvs2, 2 )   //* Qty
     Set_UV_Select_Data( uvs3, 3 )   //* Description
 
 
     //* Insert row into PACKSLIP table
     Begin_SQL()
 
       INSERT INTO PACKSLIP
         ( PALLET_NUM, ITEM, QTY, DESCRIPTION )
       VALUES
         ( :uvtPallet(N), :uvs1(C), :uvs2(C), :uvs3(C) )
 
     End_SQL()
 
     Goto Get_More
    }
 
   //* Got all rows of pallet data and inserted
   //* them with description into PACKSLIP table
   //* Commit now to close the select cursor and
   //* make permanent the new rows in PACKSLIP
   Commit_Changes()

The last SELECT statement you executed (via an End_SQL / End_SQL2 / End_Select / End_Select2 or Perform_Select command) is the statement which is valid -- any prior SELECT is destroyed as do the new SELECT.

Limit on SQL Statement Size

The size of any individual SQL statement created by the commands or input in a free-form SQL statement is limited to 4,000 characters. This includes the size of data that is brought in from the transaction or from user variables.

Binding to the Database

When TC will be connecting directly to a DB2 database (instead of using an ODBC connection to the database or not using a database at all) it is necessary for TC to 'bind' to the DB2 database before any database operations can be performed.

TC allows you the opportunity to manually perform the database binding. This is sometimes required when only certain users may have authority to perform a bind. There is now a single bind file (TCDB2.BND) that must be bound to all DB2 databases that will be used. (Prior to fix pack E for version 1.40, there were three bind files: XIS.BND, XIS_C.BND, and XISDBCOM.BND).

If you want TC perform the binding for you, you do not need to do anything beyond making sure the installation procedure was followed properly. TC responds to SQL error codes at runtime and automatically performs the SQLBIND and retry the first transaction. The .BND file must be located in the directory defined by the environment variable TC2.

Using ODBC Database Connection(s)

When TC was initially designed, DB2 was the only database type to which TC could connect. Therefore TC defaults to assuming that all database operations will be directly (natively) to DB2.

With fixpack E for version 1.40, support for ODBC connections was added to TC. Version 3.1.0 adds support for simultaneous connection to up to 24 ODBC data sources.

There are several different issues that arise with ODBC connections because the actual database type on the other end of the connection could be anything from DB2 to Oracle to SQL Server ... Although the goal of ODBC is to standardize the interface to many different database types, there are still differences between them that may need to be handled in your TC scripts. For more information about these issues please see Handling Differences Between Database Types When Using ODBC.

Regardless of the database type, because TC is a 32-bit program, it requires a 32-bit ODBC connection; it will not work with a 64-bit ODBC connection.

ODBC Performance and Deadlocks

It is sometimes thought that using ODBC to interface to a database is much slower than interfacing directly to the target database. While there is an extra layer that using ODBC requires, the actual differences in execution time is negligible. In some cases, such as some involving remote connections to databases, the ODBC implementation to that remote database may actually be faster than the native database's implementation of remote access.

TC does a couple of things to maximize performance with ODBC connections:

• TC makes sure Auto-Commit has been turned off. It is therefore necessary for your TC scripts to use the Commit_Changes command whenever database operations should be committed.

• TC maintains two statement handles to each ODBC data source for processing the various database operations found in your scripts. These statement handles are kept open for the life of the TC session.

There is one thing that can seriously degrade performance of an ODBC session if it is turned on -- the option to Trace all ODBC operations. When turned on, every database operation is logged to file which of course slows things down and consumes lots of disk space. This can be a very useful feature when trying to debug a problem. But for use in production, tracing should be turned off.

Whether or not tracing is on is determined by a setting in the ODBC Data Source Administrator settings notebook. This notebook contains a tab labelled Tracing. Make sure the options on the Tracing page are set such that tracing is not active. For more information about bringing up the ODBC Data Source settings notebook, please see Configuring an ODBC Data Source.

As was mentioned above, TC maintains two separate statement handles for processing database operations. This is also necessary in order to allow TC scripts to be able to fetch through a result set that was obtained by doing one select and at the same time do other database operations such as updates or inserts using the other handle. TC does all operations using one handle until a select operation is encountered. After the select operation, TC switches to use the other handle until another select operation is encountered. After the next select TC switches back to the first handle. TC only allows one outstanding select operation by making sure any open cursor is closed before performing a select operation.

Because SQL Server does not support more than one active statement handle per connection, TC actually has to open two separate ODBC connections to the database, one for each statement handle. As a result TC script writers have to be careful not to perform a series of database operations that would cause one handle to block, waiting on the other. The following is a scenario that would result in a deadlock:

1. An operation is performed to delete all records from a table.

2. A select operation is performed to fetch records from a different table without first committing the delete operation (this causes TC to switch to using its other handle for subsequent database operations).

3. Each record in the result set returned by the select is fetched and then inserted into the table that was cleared out in step 1.

Because the delete operation was performed using one handle and that work was not committed, the attempt to insert records into the same table would block because a different handle is being used. In order to resolve this scenario, the delete operation should be committed before the select is performed.

When using an ODBC database connection, TC watches every database operation to see how long it takes. If it finds an operation has taken longer than a certain deadlock timeout, it will assume a deadlock has occurred which will result in TC rolling back any uncommitted database operations and then shutting down.

The deadlock timeout defaults to 1 minute but can be changed to up to 60 minutes using the Deadlock_Timeout command. Please see Deadlock_Timeout.

Also be aware that a particular TC script might become blocked by database operations from other applications, including other TC scripts. So if a deadlock does occur, not only should you examine what the TC script was doing at the time to make sure the contention was not caused by the script itself but you should also check to see whether other TC scripts or other database applications have locked the same rows that the blocking TC script was accessing.

Configuring an ODBC Data Source

If TC is to use ODBC to access databases, then ODBC connections must be created to those databases before TC can access them.

Regardless of the database type, because TC is a 32-bit program it requires a 32-bit ODBC connection; it will not work with a 64-bit ODBC connection.

• On Windows, use Start -> Settings -> Control Panel -> ODBC Data Sources to configure your ODBC database connections.

• On Windows 2000, use Start -> Settings -> Control Panel -> Administrative Tools -> Data Sources (ODBC) to configure your ODBC database connections.

Once the ODBC data source is configured in Windows, your Database/DB command line argument or script command can reference that data source. However, in order to tell TC that this data soure should be accessed via ODBC instead of it being a DB2 data source to access directly, the DBType command line argument or script command must specify ODBC instead of DB2. For more information about the DBTYPE command, please see DBType.

Handling Differences Between Database Types When Using ODBC

ODBC was created as way to standardize the interface to many different database types (e.g. DB2, Oracle, SQL Server, ...). Although many things are standardized, some are not consistent between the different database types. Here are a few examples:

• DB2 supports a separate Date and Time data type while Oracle and SQL Server do not.

• In a valid date-time string DB2 expects a hyphen to separate the date and time while SQL Server and Microsoft Access expect a space.

• The function name used when getting the current date and time string is "CURRENT TIMESTAMP" for DB2, "CURRENT_TIMESTAMP" for SQL Server and "SYSDATE" for Oracle.

Quite often when a script is being written, it is for one specific database type. In this cases, these differences do not matter. However, if a single script is to work with more than one database type without changes, these differences have to be handled. TC has a few mechanisms available to allow scripts to handle these differences.

DBTYPE.INI

The basis for handling these differences is a file called DBTYPE.INI. This file contains a section for each database type that might be handled. In each section, keywords are used to define how each database type handles certain issues.

To start, TC has to figure out the database type to which it is connected. It asks the ODBC driver for the DBMS name which returns a string such as "DB2/NT", "Oracle 7", "Oracle 8.0", "Microsoft SQL Server", ... TC then maps this string to the appropriate section so that it can figure out the other traits that apply to the current database type.

Before we get into any further discussion, here is a sample of what DBTYPE.INI looks like:

 
  [DB2]
    ALIAS                 = "DB2"
    ALIAS                 = "DB2/NT"
    DATE_TIME_SEPARATOR   = "-"
    DATE_SEPARATOR        = "-"
    TIME_SEPARATOR        = "."
    CURRENT_TIME_FUNCTION = "CURRENT TIMESTAMP"
 
  [Oracle]
    ALIAS                 = "ORACLE*"
    ALIAS                 = "ORCL"
    DATE_TIME_SEPARATOR   = " "
    DATE_SEPARATOR        = "-"
    TIME_SEPARATOR        = ":"
    CURRENT_TIME_FUNCTION = "SYSDATE"
 
  [SQL SERVER]
    ALIAS                 = "Microsoft SQL Server"
    DATE_TIME_SEPARATOR   = " "
    DATE_SEPARATOR        = "-"
    TIME_SEPARATOR        = ":"
    CURRENT_TIME_FUNCTION = "CURRENT_TIMESTAMP"

Each section starts with a name enclosed in square brackets (e.g. [DB2]). This is the name by which TC will know this database type. It is the name that will be assigned to the DBTYPE data part that can be used in an If command (discussed below).

The ALIAS keyword(s) in each section specify the various strings that the ODBC driver might return when TC asks for the DBMS name. TC matches these with the response in order to figure out which section is appropriate - in other words, to which database type it is currently connected.

In order to allow for differences in the responses that the various database types might return as new versions are created, the ALIAS can be used multiple times in a section. Furthermore, the ALIAS string may contain the wild card characters * and ?. The asterisk is used to match any number of characters at the end of the string; it should not be used in the beginning or the middle of the string.

For example, Oracle 7.0 returns the string "Oracle 7" and Oracle 8.0 returns the string "Oracle 8.0". The following ALIAS statement uses a wild card character to match both strings:

  ALIAS = "Oracle*"

The ? character is used to represent a single character anywhere in the string. For example, the following alias string matches both "Oracle 8.0" and "Oracle 9.0":

  ALIAS = "Oracle ?.0"

However, this would not match "Oracle 7" or "Oracle 10.0". Therefore it is usually better to use the asterisk once you have determined a sufficiently long enough start of the string that would be unique amongst all database types.

The rest of the keywords in a database type section are used to define specific traits of that database type. These keywords are:

DATE_TIME_SEPARATOR	Specifies the character that goes between the date and time in a timestamp string that is generated by TC. TC generates a timestamp string for the Format_UV command when the field_type is TIMESTAMP or when the col_type is TIMESTAMP for the commands Select_Where, Select_Having, Setup_Insert_Field, Setup_Update_Field and Update_Where. TC also generates a timestamp string when using free-form SQL statements and the format specifier (S) is used.
DATE_SEPARATOR	Specifies the character that separates the parts of date string when it is generated by TC. TC generates a date string for the Format_UV command when the field_type is DATE or when the col_type is DATE for the commands Select_Where, Select_Having, Setup_Insert_Field, Setup_Update_Field and Update_Where. TC also generates a date string when using free-form SQL statements and the format specifier (D) is used.
TIME_SEPARATOR	Specifies the character that separates the parts of time string when it is generated by TC. TC generates a time string for the Format_UV command when the field_type is TIME or when the col_type is TIME for the commands Select_Where, Select_Having, Setup_Insert_Field, Setup_Update_Field and Update_Where. TC also generates a time string when using free-form SQL statements and the format specifier (T) is used.
CURRENT_TIME_FUNCTION	Specifies the name of the SQL function used to return the current date and time. For example, in DB2, this function is called "CURRENT TIMESTAMP" and in Oracle it is called "SYSDATE". In a TC script, when writing a free-form SQL statement (using the TC commands Begin_SQL / End_SQL or similar commands), it may be necessary to get the current date/time to insert into a table or to use in some other database operation. If the script containing this free-form SQL statement is to be run against more than one database type (e.g. DB2 and Oracle), then there is a problem trying to create SQL syntax that would be valid for both database types. To resolve this problem, TC allows the use of a mechanism similar to the user variable substitution that can be done in free-from SQL statements. For more information, please see :sqlCurrentTime Macro.

Adding Support for Other Database types to DBTYPE.INI

If you want to use TC to connect to another database type, via ODBC, other than those that are already defined in DBTYPE.INI, then all that must be done is to add another section to DBTYPE.INI file that is similar to the other sections.

First choose an appropriate name for this new database type. This will go between the square brackets. Be sure the name is unique amongst all the other sections. It can't be longer than 64 bytes.

Next you must define one or more alias strings that map the name for this type to what this database type's ODBC driver will return for the DBMS name. If you are not sure what the ODBC driver will return, you can perform the following steps to figure it out:

1. First configure an ODBC data source using the ODBC driver for the new database type. For more information about how to define an ODBC data source, refer to Configuring an ODBC Data Source.

2. If you have an existing TC script that does database operations, change it to use the new ODBC data source and the appropriate user ID and password. And if you did not already do so, make sure the DBTYPE is set to ODBC. Don't worry about what tables are in the database versus what the script references because all TC has to be able to do is to connect to the database on startup.

   If you don't have an existing TC script that does database operations, set one up using the new ODBC data source and the appropriate user ID and password. Also create a simple StartLogon script so that TC has something to compile.

3. Run the TC script so that it tries to connect to the database. If successful TC will log the message XIS083 that is similar to:

    
     XIS083:Connected to database ODBCTEST running on DB2/NT (02.01.0002)
    
   

   The DBMS name returned by the ODBC driver is the name that follows the words "running on" and comes before the parenthesis that enclose the version number. So in the example above, "DB2/NT" (without the double quotes) is the DBMS name returned by the ODBC driver.

Once you have determined what the ODBC driver will return for the DBMS name you can create the ALIAS statement. Use wildcard characters whenever possible to increase the chance for getting a match - but at the same time make sure the alias does not match any other aliases used for other database type definitions.

Finally add the appropriate values for the other keywords: DATE_TIME_SEPARATOR, DATE_SEPARATOR, TIME_SEPARATOR and CURRENT_TIME_FUNCTION.

If you do not add one or more of these keywords to the database type definition they will default as follows:

  DATE_TIME_SEPARATOR   = "-"
  DATE_SEPARATOR        = "-"
  TIME_SEPARATOR        = "."
  CURRENT_TIME_FUNCTION = ""

Using DBTYPE in an If Command

The DBTYPE.INI file is good for handling those differences between database types that can be resolved by a simple substitution of the proper character or string. However, there are other differences between database types that cannot be resolved with a simple substitution. These are situations where the SQL syntax for complex operations, particularly those involving date and time, is quite different depending on the target database type.

For example, when using DB2, if you wanted to determine the time 30 years prior to the current time, the following syntax would be part of your SQL:

  CURRENT TIMESTAMP - 30 YEARS

However, to do the same thing in Oracle, the following syntax would be part of your SQL:

  ADD_MONTHS(SYSDATE, -360)

To handle situations like these, TC allows the use of the data part DBTYPE. DBTYPE takes the value of the name of the database type from DBTYPE.INI to which TC has determined it is connected. The DBTYPE data part would typically be used in an If command. However, it can be used anywhere other data parts are allowed.

When used in an If command, the comparison must be made to one of the valid database types found in DBTYPE.INI and the comparison operator can only be one of equality or inequality: = == <> or !=. The following example shows how a TC script might handle the differences in syntax just mentioned:

  if (DBTYPE == "DB2")
   {
    Begin_SQL
 
      SELECT name, address from employee
 
      WHERE birthdate < CURRENT TIMESTAMP - 30 YEARS
 
    End_SQL
   }
 
  if (DBTYPE == "ORACLE")
   {
    Begin_SQL
 
      SELECT name, address from employee
 
      WHERE birthdate < ADD_MONTHS(SYSDATE, -360)
 
    End_SQL
   }

TC will only execute one of the above Begin_SQL / End_SQL statements, depending on which database type TC determined was being used. Of course, if neither DB2 nor Oracle was being used, neither statement would be executed.

Note that if you are using multiple ODBC connections, the DBTYPE data part will only tell you the type of the first database that was defined with Database / DB. Thus, the Get_DBType function is available to get the underlying type of any ODBC data source. The above example would need to be modified to first use Get_DBType into a variable, then use the variable in the If/Else code.

How TC Handles SQL Errors

10 SQL Error Handling Actions

When an SQL error occurs as the result of a database operation, TC may perform one of several actions to try to handle the error. The following list describes those actions, giving each a name:

DELAY_AND_RETRY	Gives time for the error condition to clear itself and then retries the script command that just failed. During the database connection phase of TC startup, this action code is one of several that will cause a looping 2 second delay and connection retry.
DELAY_RETRY_INVALIDATE	Similar to DELAY_AND_RETRY, but acknowledges that the database engine has automatically rolled-back changes and closed cursors. TC learns of this and appropriately releases its select data.
FORCE_COMMIT_RETRY	Forces a commit of all pending database operations and then retries the script command that just failed.
LOG_AND_TERMINATE	Logs information about the error that occurred and then ends the TC session.
LOG_RETURN_NO_ERROR	Logs information about the error that occurred but returns to allow the next script command to be performed.
NO_DATA	Logs an error unless a fetch is in progress. In either case, the next script command will be performed.
REBIND_DB	Performs a rebind to the database and then retries the script command that just failed. This is relevant only when TC is connected directly to a DB2 database - instead of using ODBC to connect to a DB2 database or any other database.
RECONNECT_DB	Tries to reconnect to the database (assuming there is currently no connection) and then retries the script command that just failed. During the database connection phase of TC startup, this action code is one of several that will cause a looping 2 second delay and connection retry.
RESET_RECONNECT_DB	Drops the database connection, tries to reconnect and then retries the script command that just failed. During the database connection phase of TC startup, this action code is one of several that will cause a looping 2 second delay and connection retry.
RETURN_NO_ERROR	All went well so simply return to allow the next script command to be performed.
USER_ONERROR	This is not actually an action but instead is used as a way to give an On Error String name to a native code and/or SQLSTATE that is not already handled by TC. (The script command Define_On_Error_String is another way to do this). All defined On Error Strings can be used in On_Error_Goto commands. For information, please see On Error Strings.

RC_DB2.INI and RC_ODBC.INI

TC is told which actions to perform for certain predefined SQL error values via an .INI file. If connecting to a DB2 database directly, TC looks for RC_DB2.INI; but if using ODBC to connect to the database (DB2 or other) then TC looks for RC_ODBC.INI. The appropriate .INI file must be found in the directory defined by the environment variable TC2.

The RC_*.INI files contain a series of lines that map SQL error values to one of the above actions. There are actually two ways that SQL error values can be specified: as a native database code (known as SQLCODE in DB2) or as an SQLSTATE value. It is often the case that the same SQLSTATE value is returned for several similar yet different error conditions whereas the native error code value returned in those situations is unique. For example, when connected to a DB2 database, the SQLSTATE 57011 is returned when an "Out of Application Heap memory' error occurs or when an "Out of Sort Memory" error occurs. However, the native codes for each of these errors is -954 and -955 respectively.

Because the native code is often more granular than the SQLSTATE, TC will look for a match of the native code before looking for a match of the SQLSTATE value. So when an SQL error occurs, TC will search through the table of values that were read from the RC_*.INI file and look for a match of the native code value and if none is found it will then look for a match of the SQLSTATE value. If either match is found, TC will perform the action that is assigned to the error value.

If no match is found, TC acts as if the action was LOG_RETURN_NO_ERROR.

The following are examples from the RC_*.INI files:

 
  // From RC_DB2.INI
 
    100 , SQL02000, NO_DATA             , OE NO DATA
 
   -818 , SQL51003, REBIND_DB           , OE BIND FILE TIMESTAMP CONFLICT
 
   -912 , SQL57033, FORCE_COMMIT_RETRY  , OE MAX LOCKS REACHED
 
   -803 , SQL23505, USER_ONERROR        , OE DUPLICATE RECORD
  -7008 ,         , USER_ONERROR        , OE INCONSISTENT REXX DATA
 
 
  // From RC_ODBC.INI
 
      1 ,         , LOG_RETURN_NO_ERROR , OE SUCCESS WITH INFO
 
    100 ,         , NO_DATA             , OE NO DATA
 
        , SQL08001, DELAY_AND_RETRY     , OE UNABLE TO CONNECT
 
        , SQL23505, USER_ONERROR        , OE DUPLICATE RECORD

Each non-comment line has 4 parameters, delimited by commas:

• The 1st parameter is the native code value (for DB2 this is an SQLCODE).

• The 2nd parameter is the SQLSTATE value. It is optionally preceded by the prefix string "SQL".

• The 3rd parameter is the constant specifying what action is to be performed if the error occurs. It must be one of the 10 constants given in the list above.

• The 4th parameter is called the "On Error String". It is for use in On_Error_Goto commands. It gives more meaning to the error than a simple native code value or SQLSTATE value gives. All On Error Strings must start with "OE" and cannot be longer than 32 characters.

Other comments about these .INI files:

• The three commas that separate parameters must appear in all non-comment lines, even when one of the parameters is blank. The commas are used by TC when parsing the file in order to determine the meaning of each parameter.

• Every line must specify the native code value or the SQLSTATE value or both; you cannot have both the native code value and the SQLSTATE value blank.

• In RC_DB2.INI most lines include both the native code value and the SQLSTATE value because prior to support of ODBC, TC only handled DB2 native code values (SQLCODEs).

• When looking at error values returned by different database types (e.g. DB2, Oracle, SQL Server, ...) for a given error situation the SQLSTATE value is more standardized than the native code. For this reason, most lines in RC_ODBC.INI include only the SQLSTATE value. There are a couple of exceptions to this because of the way that ODBC handles error codes.

  In most cases, a call to an ODBC function that results in an error returns SQL_ERROR (-1); TC then makes an additional call to get the native code and SQLSTATE values. However, there are two return codes that an ODBC function might return for which there is no native code or SQLSTATE value:

  SQL_NO_DATA = 100	Returned by a call, such as a fetch, that results in no records.
  SQL_NEED_DATA = 99	Returned by a call, when it needs more data for the parameters of the database operation that should be performed.

  For these 2 return codes, TC sets the native code value to the return code and leaves the SQLSTATE value blank.

  There is one last special case return code that an ODBC function might return:

  SQL_SUCCESS_WITH_INFO = 1

  This means the requested operation was successful; however, some additional information is available. For example, if string data is truncated on the right, the return code will be SQL_SUCCESS_WITH_INFO and the SQLSTATE will be set to 01004. When TC gets SQL_SUCCESS_WITH_INFO for the return code it will obtain the SQLSTATE value but it will always set the native code value to be 1 (SQL_SUCCESS_WITH_INFO). The RC_ODBC.INI file tells TC to perform the LOG_RETURN_NO_ERROR action whenever this return code occurs.

• Comments can be added to the .INI file by starting the line with double slashes. TC ignores any lines that are comments when processing the file. The following line, from the example above, illustrates the use of comments:

    // From RC_DB2.INI
  

It was mentioned earlied that the same SQLSTATE value might be returned for several similar yet different error situations. This is actually beneficial if the action that should be performed in all of these situation is the same. Thus a single entry in the .INI file could cover several different errors.

To carry this further, there may be a set of SQLSTATE values that should be handled the same way. In fact, the first two characters of an SQLSTATE value indicate a certain category of error while the last 3 characters indicate a sub-category.

TC allows the SQLSTATE value in the .INI file to be specified with less than the 5 characters that make up a full SQLSTATE value. Furthermore, if desired the characters that are omitted can be padded with asterisks so it is more obvious what is meant. However, characters at the beginning or in the middle of the string cannot be omitted nor can they be replaced with asterisks.

For example, the following lines are all valid and mean the same thing:

       , SQLHYT**, USER_ONERROR        , OE TIMEOUT EXPIRED
       , HYT**,    USER_ONERROR        , OE TIMEOUT EXPIRED
       , SQLHYT  , USER_ONERROR        , OE TIMEOUT EXPIRED
       , HYT     , USER_ONERROR        , OE TIMEOUT EXPIRED
 

If any of the above statements is found in the .INI file, TC would consider it a match when the actual SQLSTATE value returned was either HYT00 or HYT01 (or any other that starts with HYT).

RC_USER.INI

In addition to RC_DB2.INI and RC_ODBC.INI, TC will look for RC_USER.INI for additional instructions about how to handle SQL errors. This file is optional and therefore does not exist when TC is first installed.

Whenever TC is installed or a fix pack is installed, RC_ODBC.INI and RC_DB2.INI will be overwritten to allow additional default handling to be specified and to facilitate support of additional ODBC data source types. So these two default .INI files would not be good place for users to add new instructions for handling SQL errors.

If there are special error situations that need to be handled at a particular installation, RC_USER.INI is the file in which to add lines that describe how those error situations should be handled. RC_USER.INI is read before the other appropriate TC-provided .INI file. Therefore its instructions take precedence over those in the TC-provided .INI file when any return codes are in both files.

If the error situation that occurred is one that TC should be handling in its default .INI files, then that information will ultimately be added to TC's files in its next release. But for immediate resolution of the problem RC_USER.INI can be used.

The format of the contents of RC_USER.INI is the same as the other .INI files described above. There is no need to add all of the codes from the predefined file - only those that are unique or that must override the predefined action.

On Error Strings

The On Error String is an up-to-32 character name for an error situation and it is associated with a native code and/or SQLSTATE value that is returned from a database operation. The On Error String must start with the two characters, OE, so that when parsing the On_Error_Goto statement, TC can distinguish it from an SQLSTATE value or native code.

The first parameter of an On_Error_Goto statement specifies the error code that should be handled. This error code can actually be specified in one of three different ways:

• A native code value

• An SQLSTATE value

• An On Error String

The On Error String is actually a more descriptive alias for an SQLSTATE value and/or native code value. As you've seen in the examples from the RC_*.INI files above, each entry includes as the fourth parameter the On Error String which describes exactly what the error is about; if taken by themselves, it is not obvious what is meant by the specific native code value or SQLSTATE value.

While any of the 3 methods above can be used in the On_Error_Goto commands, use of the On Error String provides the most information and is also more flexible than the other 2 methods - particularly if the TC script will be used with more than one database type.

It is possible that the native code/SQLSTATE values associated with a particular On Error String in RC_DB2.INI would be different from the native code/SQLSTATE values for that same On Error String in RC_ODBC.INI. In this case, use of the On Error String instead of the native code/SQLSTATE values in the On_Error_Goto command would allow the script to work properly whether or not TC was connected to DB2 directly (DBTYPE = DB2) or using ODBC to connect to a DB2 or other database (DBTYPE = ODBC).

You'll notice the RC_*.INI files contain one or more entries that have the action parameter set to USER_ONERROR. These entries are in the file in order to give On Error String names to error codes that are not otherwise included in the file because they don't have a specific TC action assigned to them other than the default LOG_RETURN_NO_ERROR. While you could use the native code or SQLSTATE values in the On_Error_Goto command, use of the On Error String is more meaningful and flexible.

If you find there are error situations that your TC scripts need to handle with an On_Error_Goto command and the corresponding error codes are not already specifically mentioned in the RC_*.INI files, you can include the native code or SQLSTATE value directly in the On_Error_Goto command or you can use a new On Error String name, after defining that string.

New On Error String names should be defined in one of two places, the second of which is preferred:

• A new entry could be added to the RC_USER.INI file. For more information about that file, please see RC_USER.INI.

• The script command Define_On_Error_String can be added directly to your TC scripts. For more information about this command, please see Define_On_Error_String. This method is preferred over adding to RC_USER.INI file because the definition of the On Error String is part of the script that uses it; so if the script is used on multiple machines or multiple installations, there is no need to make sure the .INI file is properly updated on all of those machines.

Specifying SQLSTATE values

Your TC scripts and the supporting RC_*.INI files may reference SQLSTATE values in the following cases:

• As the second parameter of a line in one of the RC_*.INI files

• As the first parameter of an On_Error_Goto script command

• As the second or third parameter of a Defined_On_Error_String script command.

For all of these cases there are a couple of ways to specify the SQLSTATE value. An SQLSTATE value returned from a database operation has a length of 5 characters. The first 2 of those characters indicate a particular class of error and the last 3 of those characters indicate a sub-class. For example:

• HYT00 means 'Timeout expired'

• HYT01 means 'Connection timeout expired'

These are the ways that the SQLSTATE value can be specified:

• Using the exact 5 character string. For example: HYT00

  This is not valid for the Define_On_Error_String command because TC needs to distinguish the value from a native code value.

• Using the 5 character string prefixed with the string: SQL. For example: SQLHYT00.

  Many SQLSTATE values are all numeric. So adding the SQL prefix distinguishes them from a native code value. For this reason, you must use the SQL prefix when specifying an SQLSTATE value as the second or third parameter of the Define_On_Error_String script command.

• Wherever the above two methods are appropriate you may also use double quotes to enclose the string.

On occasion it may be desirable to set up error handling such that a single statement takes care of a set of related errors. For this reason, TC supports limited 'wild card' comparisons for the SQLSTATE values. TC allows you to drop 1 or more characters from the end of the SQLSTATE value so that comparisons focus only on the first few characters of the SQLSTATE value that is returned in a particular error situation. You also have the option to include asterisks for those character positions that were dropped. For example, "SQLHYT" is valid and is the the same as "SQLHYT**". However, "SQL*YT00" and "SQLHY**0" are not valid because asterisks are allowed only at the end.

To illustrate the use of truncated codes: if you wanted a single On_Error_Goto statement to handle all error situations that result in the return of any SQLSTATE that starts with HYT and direct the code to the label Handle_Timeout, you would specify the following:

  On_Error_Goto( SQLHYT**, Handle_Timeout )

The use of asterisks or truncated SQLSTATE values is allowed in the .INI files as well as in the On_Error_Goto and Define_On_Error_String scripts commands.

Fatal SQL Errors

There is list of error conditions for which TC is configured to shut down after logging an error to the display and to the error log file. These are errors for which no amount of retrying will resolve the problem. These fatal error conditions are defined in the files RC_DB2.INI and RC_ODBC.INI and are the entries that are assigned the action code LOG_AND_TERMINATE.

If you find that for certain ones of these error conditions TC should do something else instead, you can override TC's behavior by adding entries to RC_USER.INI or by using On_Error_Goto commands at the appropriate place(s) in your scripts. Neither of these methods could have been used prior to fix pack E for the 1.40 version of TC. For a complete discussion about how TC handles error codes and about how you can change that behavior, please see How TC Handles SQL Errors.

Listed below are the fatal error codes (SQLCODEs) currently defined in RC_DB2.INI. These are in effect when TC is configured to connect directly to a DB2 database (DBTYPE = DB2) instead of going through ODBC to a DB2 or other database. Refer to the online Messages Reference for complete details about these errors and possible corrective actions.

SQL Error	Description
SQL0930N	Not enough storage available to process the SQL statement.
SQL0952N	Processing was cancelled because Ctrl-Break was pressed.
SQL0953C	Not enough storage is available in the agent (server) heap to process the statement.
SQL0954C	Not enough storage is available in the application heap to process the statement.
SQL0955C	Not enough storage is available in the sort heap to process the statement.
SQL0956C	Not enough storage is available in the database heap to process the statement.
SQL0957C	Not enough storage is available in the communications heap of the database client or the DDCS/2 machine to process the statement.
SQL0958C	The maximum number of open files has been reached.
SQL0959C	Not enough storage is available in the communications heap of the database server to process the statement.
SQL0960C	The maximum number of files has been reached in the database.
SQL0961C	Not enough storage is available in the remote services heap of the database client or the DDCS/2 machine to process the statement.
SQL0962C	Not enough storage is available in the remote services heap of the server to process the statement.
SQL1004C	Not enough storage on the file system to process the command.
SQL1022C	There is not enough memory available to process the command.
SQL1034C	The database is damaged. The application has been disconnected from the database. All applications processing the database have been stopped.
SQL1042C	An unexpected system error occurred.
SQL1044N	Processing was interrupted.
SQL1086C	An operating system error <error> occurred.
SQL3005N	Processing was interrupted.

Listed below are the fatal error codes (SQLSTATEs) currently defined in RC_ODBC.INI. These are in effect when TC is configured to connect directly to any database (including DB2) via ODBC (DBTYPE = ODBC). Refer to the appropriate documentation for your database software for complete details about these errors and possible corrective actions.

SQLSTATE value	Description
28000	Invalid authorization specification
IM001	Driver does not support this function
IM002	Data source name not found and no default driver specified
IM003	Specified driver could not be loaded
IM004	Driver's SQLAllocHandle on SQL_HANDLE_ENV failed
IM005	Driver's SQLAllocHandle on SQL_HANDLE_DBC failed
IM006	Driver's SQLSetConnectAttr failed
IM007	No data source or driver specified; dialog prohibited
IM009	Unable to load translation DLL
IM012	DRIVER keyword syntax error
IM014	Invalid name of File DSN
IM015	Corrupt file data source

Processing when the Database or Host Is Unavailable

As an option, you can process transactions, remote validation requests, or data requests from DCTs even when the database or host application connection is down. For example, you can immediately respond to a validation request with information that the database is down, rather than force the terminal to wait the full host communications timeout period before it makes the same determination.

By default, TC sessions do not begin processing transactions or requests until they successfully connect to the database and/or host screen. They retry the operation every few seconds until a connection is made and then start processing transactions or requests from the terminals. If you want TC to be able to read transactions or requests and do other processing of your script without benefit of a connection to the database and/or host, put the command Run_Without_Connect (for database) and/or Run_Without_Connect (for host) anywhere in the script file.

For the database connection, if Run_Without_Connect is present TC attempts to connect to the database before allowing any transaction processing to take place, but if the connection cannot be made immediately, other processing is allowed to take place. When there is no connection to the database, any work you try to do with the database yields an error; TC always sets the native code to -1024 and the SQLSTATE value to SQL08003 while a database connection does not exist. The default RC_*.INI files also define the on-error string "OE DB CONNECTION DOES NOT EXIST" for this situation.

In your scripts, use the On_Error_Goto command to route processing of this errors to the handler for this condition (for example, script commands that do whatever is desired when the database is not available). For example:

 
    On_Error_Goto( OE DB CONNECTION DOES NOT EXIST, DB_IS_DOWN )
 
      or
 
    On_Error_Goto( SQL08003, DB_IS_DOWN )
 
      or
 
    On_Error_Goto( -1024, DB_IS_DOWN ) // Should only use this for DB2
 

Note that in Run_Without_Connect mode you should not set up On_Error_Goto statements for any errors that you expect could occur with your database. Instead make sure these errors are defined in RC_ODBC.INI with the appropriate action. When in Run_Without_Connect mode, any errors associated with the actions RESET_RECONNECT_DB or RECONNECT_DB will be handled by TC - doing the appropriate reset and connect - and then TC will convert that and any subsequent errors to the SQL08003 / -1024 error until the database connection is reestablished. Therefore, it is only necessary to set up a single On_Error_Goto statement specifying -1024 or SQL08003 in order to catch any errors that would require a reconnect to the database.

TC automatically tries to connect to the database once every minute. When a connection is finally achieved your script will resume normal processing.

An example of processing a request for a badge validation is included in Verifying a Badge against the Database.

For the host connection there are no automatic re-tries to connect. It is up to your script to attempt a host connection at the appropriate times.

Recommended Design Rules

You can create very functional applications quickly with TC, but following a few guidelines will make them more robust, bug-free, and easy to maintain:

TC User Variable Naming

As you develop an application, it becomes clear that some pieces of data input by the worker on his/her data terminal, columns from database tables and host application data are used over and over -- for example, part numbers, quantities, user IDs, etc.. Rather than use the basic 'UVnn' user variable names in your TC script use the Name_UV command to create named user variables which are used in all areas of the script:

  //* Common pieces of data
  Name_UV( UV1,     tUserID )             // User ID from DCT log-on
  Name_UV( NEXT_UV, gAS400_User )         // User ID to logon to AS/400
  Name_UV( NEXT_UV, gSQLRC )              // Error vector value from SQL command
  ...

Use global user variables only where:

• There is need to have the data persist between transactions

• When the data can truly be set in one place and is then treated as read-only

• Data needs to be passed to/from a subroutine which used as a handler for errors/events which occur during a command (such as a subroutine which is named in an On_Error_Goto command -- such calls to a subroutine cannot pass parameters).

Why Use Delimited Transaction Fields

Using semicolon-delimited fields when sending data from a DCT to the TC script is recommended as it makes it easy to add fields, change field lengths, move fields around, and avoid mistake-prone offset/length calculations. See Delimited Transaction Fields for more details.

One of the first tasks of the highest-level TC script routines is to extract the fields of the incoming transaction into named user variables for use throughout the rest of the processing for that transaction. See the example below.

Transaction Version Number

Invariably, requirements for a transaction will change after it has been rolled-out to production. This may require that the transaction format change to accomodate a new field, for example. With a 7 days X 24 hours factory operating many DCTs, it can be impossible to change over the transaction programs in all the DCTs at one time and then time this precisely with the start-up of new TC scripts. This is when it is handy to dedicate one field in every transaction to a version number representing the DCT's transaction program level. In the example in the next section, the first 3 characters of the second field contain a DCT transaction program level which the script can inspect.

Inquiry ID tags

Each time the DCT sends a transaction to which it expects an answer (to be delivered into one of its DCT-based user variables over the network), a portion of the data should be used to identify the inquiry and allow it to be matched with an incoming response. The ID tag is a value which the DCT creates and changes every time it sends an inquiry; for example, this might start with the letter 'A'and go though each letter through 'Z' and then repeat. If the DCT sends inquiry 'D' and gets a response with a 'C' (or any other letter) then it discards this response and resumes waiting for the appropriate response.

In the example below, the inquiry ID letter is appended to the DCT transaction program version as the fourth character in field 2. Therefore only the first 3 characters of field 2 are checked when verifying the version. The TC script does not check the inquiry ID letter; however, it will return the

 
  //* Extract delimited fields from incoming transaction
 
  //* First check to make sure it is fully formed from the DCT:
  If ( COUNT_TXNFIELDS #<> "7" )
   {
    //* This transaction should have 7 fields -- don't want to get
    //* a fatal TC error if we try to use a field which does not
    //* exist so handle this error...
    ...Log error, release transaction, and finish routine...
   }
 
  ...
 
  //* The first 3 characters of field 2 are the DCT transaction program version, while
  //* the fourth character is the inquiry ID value.
  Set_UV_Xact_Data( uvtTag, TXNFIELD2, 0, 0 )
 
 
  If ( uvtTag(0, 3) == "100" )
   {
    //* This transaction came from a terminal still running the original set
    //* of transaction programs -- version 1.00
    Set_UV_Xact_Data( uvtUserID, TXNFIELD3, 0, 0 )
    Set_UV_Xact_Data( uvtPart, TXNFIELD4, 0, 0 )
   }
  Else...
 
  (Handle other versions with differing delimited field assignments)
 
  (Process the transaction and set up all but the last user variable response.
 
  //* The final user variable to be set in the terminal will contain the tag that
  //* we received.  The terminal should have cleared its user variable 99 and should
  //* be waiting for user variable 99 to be set.  Once set, the terminal should
  //* ensure that the contents of user variable 99 match the tag that was sent up.
  //* This tag includes the 3-byte version number followed by the inquiry ID byte -
  //* just as it was received by the TC script.
 
   Send_Term_UV_Data( 99, uvtTag )
 

Creating the Script Command File

You use the script command file to tell TC what processing steps to take with each transaction, remote validation request, or data request it receives. The command file is simply an ASCII flat file, created with one of many available text editors on any system.

The command file is compiled by TC each time TC starts up. This compilation ensures that execution time is quick, with minimal amounts of searching and parsing to consume time and resources during production processing. The compiler issues error messages if it detects an error in your scripts.

You can use the command Imbed to imbed separate text files into your primary script file. This is useful when you have common script file construction elements that you want to use in several different overall scripts. The Imbed command allows the use of environment variables in the file path.

If you have used or will use the IMBED command at some point, you may need to to create a single listing file that includes all of the imbedded files. This can make it easier to search through your scripts or to analyze them. New with fix pack D of version 1.4.0 is a utility, Using the Utility IMBEDSCR.EXE to Create a Single Listing File, that can be used to create this listing file.

TC Script Examples

The following examples show how to write the command steps for various common tasks. The [n] markings on the lines direct you to the description of what the line of the command file is doing.

Several examples of common uses for Transaction Connection are included in the next sections. When reading this document in its on-line documentation format, on each example you can bring up hypertext links to explanatory text by double-clicking on the double-asterisk (**) (1) marks located after certain statements of the command scripts. For the hardcopy version, refer to the footnote for the statements.

When creating your command script file, you can copy and paste these examples from the documentation into your script files.

Inserting a Record into a Table

StartFunctionGroup( SHOP_FLOOR )        //[A](**)
(2)
 
    // F1 key transaction inserts a new part number into the database table
 
StartKey( F1 )                        //[B](**)
(3)
 
Insert_DB_Table( PART_NUMBERS )       //[C](**)
(4)
 
Setup_Insert_Field( PART_NUMBER, CHARACTER, TXNDATA, 0, 10) //[D](**)
(5)
Setup_Insert_Field( QUANTITY, NUMERIC, NULL, 0, 0, 0.0)     //[E](**)
(6)
Setup_Insert_Field( UPDATE_TS, TIMESTAMP, TIMESTAMP, 0, 12) //[F](**)
(7)
Perform_Insert ( Insert_Error_1 )   //[G](**)
(8)
 
Commit_Changes(COMMIT_ERROR)        //[H](**)
(9)
Goto End_F1                         //[I](**)
(10)
Insert_Error_1:                       //[J](**)
(11)
 
End_F1:                               //[K](**)
(12)
Release_Xact()                      //[L](**)
(13)
 
EndKey()                              //[M](**)
(14)
 
StartKey( Fn )                        //[N](**)
(15)
 
    ...
 
EndFunctionGroup()                      //[O](**)
(16)

Updating a Record in a Table

StartFunctionGroup( SHOP_FLOOR )         //[A](**)
(17)
 
    // F2 transaction adds quantity from transaction to the
    // current quantity in stock
 
StartKey( F2 )                        //[B](**)
(18)
 
Update_DB_Table( PART_NUMBERS )     //[C](**)
(19)
 
Setup_Update_Field( QUANTITY, NUMERIC, TXNDATA, 10, 8, QUANTITY+) //[D](**)
(20)
Setup_Update_Field( UPDATE_TS, TIMESTAMP, TIMESTAMP, 0, 12)  //[E](**)
(21)
Update_Where( PART_NUMBER, CHARACTER, = , TXNDATA, 0, 10 )   //[F](**)
(22)
 
Perform_Update ( Update_Error_2 )   //[G](**)
(23)
Commit_Changes(COMMIT_ERROR)        //[H](**)
(24)
Goto End_F2                         //[I](**)
(25)
Update_Error_2:                       //[J](**)
(26)
 
End_F2:                               //[K](**)
(27)
Release_Xact()                      //[L](**)
(28)
 
EndKey()                              //[M](**)
(29)
 
 
StartKey( Fn )                        //[N](**)
(30)
      ...
 
 
EndFunctionGroup()                      //[O](**)
(31)

Querying the Database Table

StartFunctionGroup( SHOP_FLOOR )                     //[A](**)
(17)
 
    // F3 transaction asks for current quantity of a part number
 
StartKey( F3 )                                     //[B](**)
(32)
 
Select_From_DB_Table( PART_NUMBERS )             //[C](**)
(33)
 
Select_Column ( QUANTITY )                       //[D](**)
(34)
 
Select_Where( PART_NUMBER, CHARACTER, = , TXNDATA, 0, 10 ) //[E](**)
(35)
 
Perform_Select ( Select_Error_3 )                //[F](**)
(36)
Perform_Fetch( No_such_pn )                      //[G](**)
(37)
Clear_UV(UV1)                                    //[H](**)
(38)
Append_UV_Select_Data( UV1, 1, No_such_pn, 10.3) //[I](**)
(39)
Send_Term_UV_Data( UV1, 10)                      //[J](**)
(40)
 
Goto End_F3                                      //[K](**)
(41)
Select_Error_3:                                    //[L](**)
(42)
      ...
 
Goto End_F3                                      //[K](**)
(41)
 
    No_such_pn:
Append_UV_Kbd_Data( UV1, "Sorry, no such part")  //[M](**)
(43)
 
Send_Term_UV_Data( UV1, 10)                      //[J](**)
(40)
 
End_F3 :                                           //[N](**)
(44)
Release_Xact()                                   //[O](**)
(45)
 
 
EndKey()                                           //[P](**)
(46)
 
StartKey( Fn )                                     //[Q](**)
(47)
      ...
 
EndFunctionGroup()                                   //[R](**)
(48)

Using Free-Form SQL

StartFunctionGroup( SHOP_FLOOR )               //[A](**)
(17)
 
    // F4 transaction asks for current quantity of each of the
    // three part numbers starting with the part number specified
    // in transaction field 1 from the terminal.  This uses
    // TC's automatic scanning of the transaction record for
    // fields delimited by semi-colons
    // (for example, data1;data2;data3;...),
    // taking all data up to the next semi-colon field separator.
 
StartKey( F4 )                              //[B](**)
(49)
Append_UV_Xact_Data( UV1, TXNFIELD1, 0, 0)  //[C](**)
(50)
 
      Format_UV( UV1, NUMERIC )
 
Begin_SQL()                               //[D](**)
(51)
 
SELECT PART_NUMBER, QUANTITY            //[E](**)
(52)
          FROM PART_NUMBERS
          WHERE PART_NUMBER BETWEEN :UV1 AND (:UV1 + 2)
 
End_SQL(SQL_error)                        //[F](**)
(53)
 
Perform_Fetch( Fetch_error )              //[G](**)
(54)
      Set_UV_Kbd_Data( UV1, "Part Num:")
      Append_UV_Select_Data( UV1, 1, No_more_data_4 )
      Append_UV_Kbd_Data( UV1, "  Quantity:")
      Append_UV_Select_Data( UV1, 2, No_more_data_4 )
      Send_Term_UV_Data( UV1, 10)
 
      Perform_Fetch( Fetch_error )
      Set_UV_Kbd_Data( UV1, "Part Num:")
      Append_UV_Select_Data( UV1, 1, No_more_data_4 )
      Append_UV_Kbd_Data( 1, "  Quantity:")
      Append_UV_Select_Data( UV1, 2, No_more_data_4)
      Send_Term_UV_Data( UV1, 11)
 
      Perform_Fetch( Fetch_error )
      Append_UV_Kbd_Data( UV1, "Part Num:")
      Append_UV_Select_Data( UV1, 1, No_more_data_4 )
      Append_UV_Kbd_Data( 1, "  Quantity:")
      Append_UV_Select_Data( UV1, 2, No_more_data_4 )
      Send_Term_UV_Data( UV1, 12)
 
    SQL_error:
No_more_data:                             //[H](**)
(55)
 
Close_Cursor()                            //[I](**)
(56)
      Clear_UV ( UV1 )
Append_UV_Kbd_Data( UV1, "Report Done")   //[J](**)
(57)
      Send_Term_UV_Data( UV1, 13)
 
      Release_Xact()
 
    EndKey()
 
  EndFunctionGroup()

Multiple ODBC Connections

// Note that database connection information must be defined in the script -- not on the
// command line -- when you are using multiple connections!

// Only DBType 'ODBC' allows multiple database connections 
// This one configuration line rules for all database connections
DBType( ODBC )

// Use DB / Database command to indicate which ODBC data sources you want to 
// use in your TC script.  
// The first parameter is the datasource name in Windows ODBC Datasources.
// The second parameter is an optional override alias names by which you will refer to the
// data source in subsequent TC script executable commands.  
// If you do not specify an alias then you will be using the actual Windows data source name in
// your script's executable commands (in effect, the alias is equal to the real name).  
// By specifying an alias which is different from the actual data sourc name you 
// can create multiple connections to the same data source, and thus have multiple
// Selects open to the same database. 

// Datasource 1:  oDCLIBdb2 is an ODBC data source that points to a DB2 database
DB ( oDCLIBdb2 )   

// Datasource 2: This is a second connection to that DB2 database
DB ( oDCLIBdb2, AnotherAliasForDB2 )    

// If needed to override the user credentials that are executing Transaction Connection, 
// specify the user ID and password for a previously-defined DB/Database alias.
// Notice here that when the DB/Database was defined the alias defaulted to the real name.  
// The alias must be used in these commands -- and all other commands EXECEPT DB/Database.  
// You can set the userID and/or password for each data source alias independently.
DBUserid( hornernw, oDCLIBdb2 )
DBPassword( pa55w0rd, oDCLIBdb2 )   // Or DBEncryptedPW can be used

// Datasource 3: A MS SQL Server data source, aliased to SQLServDB 
DB ( oDCLIBsql, SQLServDB )      
  
  
// Test it....  
StartLogon()

 Call DoIt()

EndLogon()


Sub DoIt()

   Declare( DB2_EMPLOYEE )
   Declare( DB2_GROUP ) 
   Declare( YY) 
   Declare( SQL_GEO ) 
   Declare( XX ) 
   Declare( uvName)
   Declare( uvAcro)
   Declare( uvLCL_GBL)
   
  
   // Select from the DB2 datasource, using alias defaulted from real name (Note Begin_SQL and Begin_SQL2 are interchangeable):
   Begin_SQL2()
   
      SELECT EMPLOYEE FROM DCLIB.EMPLGRP
      
   End_SQL2( oDCLIBdb2 )   // <<== Use the new '...2' flavor of End_SQL to indicate    
                           // that first parm is a required DB alias.  The optional 
                           // 2nd parm is the traditional error vector. 
   
   //Select from the same DB2 database, but using a different alias, and thus
   //a different set of connections/cursors/results set, etc. 
   Begin_SQL2()
   
      SELECT WORK_GROUP FROM DCLIB.EMPLGRP
      
   End_SQL2( AnotherAliasForDB2 )       
   
  
   // Cause fetch from Select from oDCLIBdb2 above.  Note ...2 flavor of the command, with
   // alias as required first parm and the traditional optional error vector 
   Perform_Fetch2( oDCLIBdb2, errlbl ) 
    
   // Cause fetch from AnotherAliasForDB2 Select above
   Perform_Fetch2( AnotherAliasForDB2, errlbl ) 
   
   // Use fetched row from oDCLIBdb2 select.  Again, the ...2 flavor of this command
   // requires the data alias as the first parm.
   Set_UV_Select_Data2( oDCLIBdb2, DB2_EMPLOYEE, 1 ) 
   
   // Use fetched row from AnotherAliasForDB2 select     
   Set_UV_Select_Data2( AnotherAliasForDB2, DB2_GROUP, 1 ) 
   
   
   //* Commit/close the selection from  oDCLIBdb2
   Commit_Changes2 ( oDCLIBdb2 )
   
   // Test no commit on 2nd connect to db2 db -- it will be forced closed when the script ends
   
   
   
  
   // Work with SQL Server datasource.
   // Note that user's default database has been configured in SQL Server Studio to be the 
   // desired database (otherwise the database name would be needed in this SQL as a pre-pended
   // schema identifer (e.g. DCLIBsql.dbo.Geographies)

  Begin_SQL()
  
     SELECT NAME FROM dbo.Geographies
     
  End_SQL2( SQLServDB, err2 ) 
  
  Perform_Fetch2( SQLServDB ) 
  
  Set_UV_Select_Data2( SQLServDB, SQL_GEO, 1 )   
  
  // Again, the ...2 suffix flavor of this command requires DB alias as firt parm.
  Close_Cursor2 ( SQLServDB ) 
  
  Commit_Changes2( SQLServDB )       
  
   
  
  err2:
  
  // The 'stick-built' insert sequence is the same for use with 
  // any database alias UNTIL you get to the final Perform_Insert2 -- where
  // you tell it where to actually apply the SQL statement that has been 
  // built-up with the prior commands.  Note you can only 'stick-build' the
  // insert for a single database at a time because of a shared buffer under the covers.
  // Also note that only INSERT is supported -- the stick-built Select and Update do not
  // have a ...2 flavor command and will thus work against the first database defined.
  Insert_DB_Table( dbo.Geographies )
  
  Set_UV_Kbd_Data( uvName, "AFRICA" )
  Set_UV_Kbd_Data( uvAcro, "AF" )
  Set_UV_Kbd_Data( uvLCL_GBL, "LCL" )
  
  Setup_Insert_Field( NAME, CHARACTER, uvName, 0, 0)
  Setup_Insert_Field( ACRONYM, CHARACTER, uvAcro, 0, 0) 
  Setup_Insert_Field( LCL_GBL, CHARACTER, uvLCL_GBL, 0, 0) 
  
  Perform_Insert2( SQLServDB )
  
  Commit_Changes2( SQLServDB ) 

EndSub()



Sub errlbl()

  Log_Error( "error on fetch" )
  
EndSub()

Handling Remote Validation Request

StartVal(BADGES.VAL)                             //[A](**)
(58)
 
    Clear_UV(UV1);
 
Select_From_DB_Table( EMPLOYEES )             //[B](**)
(59)
    Select_Column( FIRST_NAME )
 
    Select_Where( BADGE_NUMBER, CHARACTER, =, TXNDATA, 0, 0)
 
    Perform_Select(SQLerror)
 
Perform_Fetch(No_such_badge)                  //[C](**)
(60)
 
    Append_UV_Kbd_Data( UV1, "Thank you, ")
Append_UV_Select_Data( UV1, 1, No_such_badge) //[D](**)
(61)
 
    Close_Cursor()
 
    // will execute this if badge number was found
Send_Term_UV_Data( UV1, 10 )                  //[E](**)
(62)
    Send_Term_VResp( PASS )
 
    Goto End_badge
  // will branch to here if no such badge
No_such_badge:                                //[F](**)
(63)
 
    Append_UV_Kbd_Data(UV1, "Sorry, your badge number is invalid")
Send_Term_UV_Data( UV1, 10, SYNCH)          //[G](**)
(64)
Send_Term_VResp( FAIL )                     //[H](**)
(65)
 
    Goto End_badge
 
  SQLerror:
 
    Append_UV_Kbd_Data(UV1, "System error #001 -- Call SysOp @ 3-9233")
Send_Term_UV_Data( UV1, 10, SYNCH)          //[G](**)
(64)
Send_Term_VResp( FAIL )                     //[H](**)
(65)
 
  End_badge:
 
  EndVal

Using the Utility IMBEDSCR.EXE to Create a Single Listing File

New with fix pack D is a utility program, IMBEDSCR.EXE, which is useful if your scripts are stored in several command files and you use the IMBED command to link them altogether. IMBEDSCR.EXE allows you to generate a single listing file that includes all of the imbedded files. The listing shows the line number from each imbedded file along with a letter indicating the imbed level of that file (A for the top level, B for the next level, ...)

To generate a single listing file which includes all imbedded files in the listing, issue the following command:

  imbedscr source_file

The output file will have the same 'file name' (before the period) as the input file, but the extension of the output file will be .LST - unless the extension of the input file is already .LST in which case the extension of the output file will be .OUT.

Initially this tool generated a listing file that could not actually be run by TC. But the latest version generates a 'runnable' output file. This might be useful if the set of scripts need to be sent to a colleague to illustrate something or if the set of scripts need to be sent to IBM so that a problem can be replicated.

If you prefer to get a listing with line numbers, then you can add a second parameter, listing, to the command line. For example:

  imbedscr erp_ow.scr listing

Starting Transaction Connection

If your TC scripts will be using any functions that are in the category of Host Screen Interaction Functions, TC requires that Personal Communications (PCOMM) or another provider of the Emulator High Level Language Application Programming Interface (EHLLAPI) functions in ACS3EHAP.DLL be installed prior to running those TC scripts.

Likewise, if your TC scripts will be using any Database Insert/Query/Update Functions, TC requires that the appropriate database software (a database to be accessed via ODBC or IBM DB2, accessed directly) already be installed.

For information about configuring an ODBC data source, please see Configuring an ODBC Data Source.

Also make sure that the session in which TC will be running has the proper access authority in order to be able to perform operations on the databases.

If your scripts will be using any DCConnect API or a mailbox name other than NO_DCCONNECT, then TC requires that DCConnect Toolkit or Server be installed. In this case, TC expects the DCConnect Server to be running before it will run any scripts. Similarly, any TC session will shut itself down when it detects that the DCConnect Server has been shut down.

Starting TC from the OS/2 STARTUP.CMD

• If the TC session is interacting with a host system, you must log on to the host system. For example:

    REM AS/400 userid, password, partner LU alias
    LOGON userid /P:password /N:as400node
  

• If the TC session is interacting with a database, you must log on to the database. For example:

    REM Database userid and password
    LOGON userid /p=password
  

• If the TC session is interacting with DCConnect, you must start up DCConnect. For example:

    cd \dcconn\bin
    start dcxcpos2
  

After including the necessary commands mentioned above, include the command(s) to start the TC session(s). For example:

  start tc2 @ mapicsxa.scr

Note: The TC session(s) can be set up to be started by DCConnect. If that is the case, you do not include in the STARTUP.CMD file any commands for starting TC sessions.

Starting TC from a Command Line

The TC sessions can be started from the command line or in a .CMD file as follows:

  TC2 <script command file> /MAILBOX=<mailbox>|REMOTE_VALIDATION|DATA_REQUEST|NO_DCCONNECT /DB=<database> /CNTLR=<controller id> /APPL=<application> /DBTYPE=NONE|DB2|ODBC
                     /EMULTYPE=NONE|CM|PCOMM /DBUSERID=<user_id> /DBPASSWORD=<password> /TRACE|/NO_DISPLAY /XML_SENDER=<DLL_name:Function_name>
or
  TC2 @ <script command file>

Note 1:The first example above is spread over two lines for typographical reasons only. When supplying the parameters on the command line, they should all be entered on one line.

Note 2:Support for the Talk Thru option (TT) was discontinued after version 3.1.1 of TC.

In the first example for each of the above cases, several parameters are explicitly stated on the command line. Some of the parameters are optional and are explained below. The angle brackets are NOT part of the syntax that should be typed on the command line or in a .CMD file. Parameters for TC are free style and require the keyword to identify the parameter type. All TC keyword parameters are optional and revert to a default value if not entered.

In the second example for each case, the only parameter is the name of the script command file immediately preceded by the '@' character. Using this method the parameters that otherwise would have been defined on the command line are instead defined in the script command file or one that is imbedded by it. The following script commands are used to define the values for these parameters:

 
    mailbox()
    session()
    cntlr()
    application()
    database()
    db()
    emultype()
    dbtype()
    dbuserid()
    dbpassword()
    xml_sender()
 

In all cases, the <script command file> is the name of the script command file for this TC session. This file is a script that instructs the TC session what you want to do with each transaction, validation request or data request. Creating the Script Command File describes how to create your command script file.

Note: Throughout this documentation, the terms 'script file' and 'command file' are used interchangeably.

If specifying the parameters on the command line as indicated previously, the parameters should be specified as follows:

<mailbox>	This is the name of the DCConnect mailbox that this TC session should use when connecting to DCConnect. The name must match exactly, including capitalization, the mailbox name that has been created in DCConnect. If your TC session is processing validation requests instead of transactions, then you should specify the following keyword: REMOTE_VALIDATION instead of an actual mailbox name. In this case, the TC session determines which validation files should be handled from all of the StartVal commands that are encountered in the script. The application name parameter can be used to override the default application name that the TC session would otherwise use when registering with DCConnect to receive validation requests. The default application name is based on the controller ID. If your TC session is processing data requests instead of transactions or validation requests, then you should specify the following keyword: DATA_REQUEST instead of an actual mailbox name. In this case, you must specify an application name on the command line, or in the script. The TC session uses that application name when registering itself with DCConnect to handle data requests. See Transaction, Remote Validation, or Data Request Modes for additional information. If you want to run a TC session that does not handle transactions, validation requests or data requests, use any of the following keywords: NONE NO_DCCONNECT NO_DCC/2 in place of the mailbox name. (This is also the default if the /MAILBOX parameter is not used on the command line and the mailbox() command is not used anywhere in your script files). This can be useful if your TC session is going to be performing only a simple operation on an interval basis, such as downloading files from an AS/400 twice a day. As an example: /MAILBOX=NO_DCCONNECT
<session>	This is the 'short name' of the PCOMM terminal emulation session to which this TC session tries to connect. This is a single character, for example: /SESSION=A If no /SESSION parameter is supplied the session will not attempt to connect to a host screen.
<controllerid>	This is a single character to use as an arbitrary controller identification. This character is used in the name of the error log file, transaction log file, and trace log file that can be generated by each TC session that is running. If the TC session is processing remote validation requests then the controller ID is part of the default application name used when the TC session registers with DCConnect to receive validation requests. Each TC session should be started with a unique controller ID. This parameter is optional unless multiple TC sessions are running at the same time. The default controller ID is 'Z'.
<application>	This parameter can be specified if the TC session is processing validation requests or data requests. It is ignored if transactions are being processed. If the TC session is processing validation requests, the application name specified here overrides the default name that would be based on the controller ID. This name is used by the TC session when it registers with DCConnect to receive validation requests. If the TC session (i.e. 'server') is processing data requests, the application name is required. This name is used by the TC session when it registers with DCConnect to receive data requests. All terminals or other TC sessions acting as the clients that make the data requests must specify the TC 'server' session's application name in the request. DCConnect uses that application name to route the request to the 'server' application that has registered itself using that name. The application name can be up to 32 characters long.
<database>	This is the name of the database with which this TC session is working. The database name can be up to 128 characters and, more importantly, it must match the name of a database that has already been created.
<user_id>	This is the name of a valid user id on the system that is the target of the database connection. This may be 1-127 characters in length. This provides database user-id and password information to be passed on the database connection. This is analogous to the command line SQL statement: CONNECT TO database USER user_id USING password.
<password>	This is the password which is valid for user_id on the system that is the target of the database connection. password may be 1-127 characters in length. This provides database user-id and password information to be passed on the database connection. This is analogous to the command line SQL statement: CONNECT TO database USER user_id USING password.
/DBTYPE	This optionally specifies the database type to which TC will be connecting. To indicate that TC will be connecting directly to an IBM DB2 database (instead of using ODBC to connect to it), specify the following keyword: DB2 If TC will be using ODBC to connect to the database, including DB2, then use the following keyword: ODBC If you are not going to be doing any database operations in the command scripts, specify the following keyword: NONE If the DBTYPE keyword is not used on the command line or in the scripts, the default will be DB2 if the /DB keyword or Database/DB script commands are used. Otherwise the default is NONE. For more information about defining the database type in the script files, please see the discussion of the script command DBType.
/EMULTYPE	(TC only ) This optionally specifies the host screen emulation support. To indicate the emulation support you are using specify one of the the following keywords: PCOMM ( Personal Communications ) CM ( Communications Manager/2 (OS/2 only) ) Note 2:Support for the Talk Thru option (TT) was discontinued after version 3.1.1 of TC. If you are not going to be doing any screen emulation operations in the command scripts specify the following keyword: NONE If the EMULTYPE keyword is not used the default will be NONE.
TRACE	This optional parameter is used to turn on execution or compile tracing for debug purposes. Refer to the Trace command for additional information. If used, this parameter should appear at the end of the parameter list. If TRACE is specified, NO_DISPLAY should not be used.
NO_DISPLAY	This optional parameter is used to improve processing speed by turning off the display of each executed step. Refer to the No_Display_Execute command for additional information. If used, this parameter should appear at the end of the parameter list. If NO_DISPLAY is specified, TRACE should not be used.
<DLL_name:Function_name>	This parameter is optional but generally necessary when using XML commands. The default DLL is TCXML.Dll and function is SendXMLMessage. See XML_Sender for additional information.

Multiple TC Sessions

You can start multiple sessions (instances) of TC. This is useful to:

• Process transactions or requests against more than one database. Each TC session works with a single database.

• Provide multiple parallel resources to handle the traffic of transactions or requests against a single database. The number of TC sessions working with a database is limited only by the database software resources - many of which you can configure in the database software to allow more users to connect to a database.

• Provide multiple parallel sign-ons to the host-based screen application, thereby increasing the overall transaction rate to the host application, or having each sign-on handling transactions bound for a different host application input screen.

• Provide transaction processing and request processing on the same computer.

Each TC session must be started with a unique mailbox; DCConnect does not allow more than one application to request data from the same mailbox.

Each TC session should have a unique controller ID. This ID is used as the 'x' in the TC2ERRx.LOG error log file, TC2TRCx.nnn trace file, and TC2XACx.LOG transaction log file that are opened by each session. If the TC session is handling remote validation requests, the Controller ID is used as part of the default application name used when registering the TC session with DCConnect.

If more than one TC session is handling data requests, each must specify a unique application name.

TC Session Window

Each session of TC runs in its own GUI window. This window provides user controls for viewing current and past operation and error messages, changing operating modes, reviewing operating parameters, and shutting down the session.

When the session is Shutdown, the window remains so that you can view the status of the logoff commands. A second Shutdown must be issued to completely end the TC session (unless the Close_When_Complete script command is used).

Title Bar

The title bar tells you the TC program name and a bit about its operation status. The title bar shows:

  Transaction Connection:  Compiling

during the script compile process. When script is executing, you see:

  Transaction Connection Controller n

with n replaced by the controller ID character you specified on the command line. Note that you can change this text via the Title script command.

When the TC session has completed, the title bar changes to:

  Transaction Connection:  Completed

At this point, you can scroll any of the message boxes to see what was happening prior to the session shutting down, and then double-click on the window icon in the upper-left corner to close the window.

Menu Bar

The Menu Bar across the top of the window provides pull-down menu choices that include:

• Session

  View a table that lists all the operation parameters obtained from the command line startup of the session and from the script file.

• Shutdown

  Perform one of three kinds of shutdowns:

  • A Normal shutdown begins after the current command completes. It performs the StartLogoff script, if one is defined in the scripts.

  • An Abnormal shutdown begins immediately and does not run the StartLogoff script.

  • Shutdown When Idle waits until the current script has completed and then begins the shut down process, including running the StartLogoff script, if one is defined in the scripts. If no script is currently running, this is the same as a Normal shut down.

  Once the shutdown has completed, the title bar and task list show the window as Completed. You can review any final messages before completely closing the window. However, if your script includes the Close_When_Complete command, the window will be closed as well.

• Display

  Toggle On and Off the Display mode of the session. With Display checked, each step of your script is displayed as it is compiled or executed. With Display unchecked, only compile errors and execution timing data are displayed.

  Once a script has been completed and debugged, you should run with Display unchecked. This provides for much faster compile times and transaction processing times. TC sessions default to Display checked. You can either manually toggle the status by clicking on the menu item, or you can cause it to start with Display unchecked by including the command No_Display_Execute in the script (preferably near the top of the script so it takes effect early in the compile process).

  Note: With Display checked the TC session will also display any outgoing or incoming web service request, as well as information about current XML document navigation during WS_EnterElement command execution. This is helpful for debugging, but the modal pop-up windows are disruptive so you will generally want to run with the display mode turned off.

• Trace

  Toggle On and Off the Trace mode of the session. With Trace On checked, various trace data are logged to the TC2TRCx.nnn file (as appropriate for the TC session, where x is the controller ID character assigned to the session).

  Trace On defaults to unchecked (inactive). You can manually click on the On menu item to toggle it on, or you can include the command Trace anywhere in your script to have Trace active as soon as TC starts.

  Turning on Trace automatically selects Display On.

  Reload XML Logging Parameters is available only if the command XML_LoadLoggingParameters has been run. This command specifies the file from which the logging parameters should be loaded and then loads them. This menu option is used to reload the current logging parameters from the same file without have to stop the TC session. This can be used to increase the loglevel temporarily, for example.

• About...

  This menu item shows you version information for TC.

Stopping Transaction Connection

TC can be stopped by any of several methods:

• Select Shutdown from the action bar on the window. A Normal shutdown causes any Logoff script to be run prior to shutting down. An Abnormal shutdown skips the logoff and immediately ends TC. You could also specify to shut down When Idle so that the currently running script, if any, completes before the session shuts down.

• Double-click on the system menu icon in the upper-left corner of the window (or select Close from this menu).

• Select Close from the system menu for the window through the OS/2 task list or appropriate icon on the Windows task bar.

• Cause the End / End_TC command to be executed in your script.

If the Password command has been used to set a password for the window, you are prompted for this password before you can end the TC session. If there is no password, you are asked to verify that a shutdown is desired.

To give you a chance to review any messages in the TC windows, the TC session stops with the message Completed in the title bar of the window (unless the script command Close_When_Complete is used). Select shutdown/close again to complete the shutdown.

Any non-committed unit of SQL work is rolled back automatically as the session stops. If your script had not caused the last transaction read to be released, this transaction is read again from DCConnect the next time this TC session starts. No automatic transaction release is done upon a session shutdown.

Measuring and Improving Performance of TC Scripts

Execution Performance Timings

A window on the TC screen shows you the sequence of commands as they are executed for each script(assuming Display On is enabled in the TC Window). At the end of the script, a timing report is shown that provides some idea of throughput and what systems are taking the most time.

The Idle time is the amount of time that TC has been waiting for another transaction/request from DCConnect or to wait for the next StartTime, StartInterval or StartTimeout script to execute. When DCConnect has another transaction/request already in the queue, this time is usually negligible. If you see a large value, this indicates there was no transaction/request waiting in the queue, and therefore TC was waiting for this time period for some activity from a terminal or application.

The Tot.Txn.time shows the total time used from when the transaction/request was received from DCConnect or timed event occurred until the script completed. This includes the script's processing time, time spent waiting for the host screen to unlock, database processing time or time for an XML message to be processed.

The External time gives the time taken by database processing and/or time taken waiting for the host application screen to unlock and/or time spent waiting for a reply to an XML message. This is a component of the Tot.Txn.time discussed above.

With tracing turned on, the TC2TRCx.nnn file includes the approximate execution time in milliseconds for each command of the script. This is listed at the left margin of the trace listing file.

Your scripting has programmatic access to the execution time of the last script command/step, the total transaction time, and the external time via the data parts EXECUTION_TIME_LAST, EXECUTION_TIME_TOTAL, and EXECUTION_TIME_EXTERNAL.

Increasing Processing Speed

Execution Information Display

By default, the TC displays each step on the screen as it is executed. This is useful for seeing what is going on, but it does consume substantial processing time. You can improve processing speed by turning off this display using the command No_Display_Execute anywhere in your script command file. In applications where the database work is done quickly, this can increase throughput by as much as 10%. When database processing time is more substantial, the improvement is less.

Prior to version 3.1.0f, when Display mode was in effect, several web service commands (e.g. WS_SendRequest, WS_SendResponse) would show a popup with information about the command. In version 3.1.0f, displaying of these popups has been turned off by default. If there is a need to show these popups, the command WS_DisplayExecutePopups can be added to the scripts.

Multiple TC Sessions

To take advantage of the concurrency capabilities of DB2 and other database types, use several TC sessions processing transactions/requests from DCConnect against the same database, and even the same tables. This takes full advantage of slack time in the database engine when one session is off waiting for a DCConnect function call to return, and so forth. You can have multiple sessions processing the same types of transactions/requests using the same script, with workload divided by assigning physical terminals to one of the several parallel sessions, or you can have each session process specific types of transactions/requests from all terminals, or a combination of these methods.

Database Performance

For best database performance:

• Install two hard drives in the PC. Place the database table on the first drive and the database log files on to the second drive. This minimizes head travel distance as the database software alternates writing to the log files and to the actual database. A third drive would be of use to store the DCConnect mailbox.
• Install a sufficient amount of RAM memory in the PC. An insufficient amount of memory causes the system to page information to the hard drive and reduces system performance.
• It is recommended that you perform benchmark testing and tune database parameters, such as, Row Buffer pool size, lock list size, and the sort heap size.
• Keep all tables in the same database, even if they are unrelated tables.

If using an ODBC connection to your database and performance is very slow, you may have ODBC tracing turned on. For instructions about how to check whether this option is on, please see Using an ODBC Database Connection.

Sending Data to the Host Screen

Text data being copied to the screen is copied directly to the presentation space, instead of being sent on a key-by-key basis. The only exception to this is when a control key is being sent. When control keys are present in the data stream, the key-by-key method must be used (this is an EHLLAPI restriction). For maximum performance, you would not want to combine a long string with an ENTER key control sequence in a user variable being sent to the host. You should send the string first, then separately send the control key(s). If there are any control characters in the data, TC automatically uses the key-by-key method of sending.

For best performance, especially when sending data to many widely scattered locations on the host display, use the Send_To_Host command rather than any of the other Send_Host... commands.

Multiple DCT Transactions to a Host Screen

TC commands enable you to take multiple transactions from the DCTs and safely and efficiently use them to fill in a multi-entry host application screen. For example, a host screen may have been designed for a human key-punch operator to input a stack of hardcopy time sheets. This screen has many lines to input many sets of start/stop times. For the DCTs, each input of a start/stop time is an individual transaction to DCConnect. You may want to increase raw throughput to a customized host screen by sending multiple, unrelated transactions with each press of the Enter key. The example below shows how commands can be used to transcribe each transaction to a line of the host screen, while keeping the transaction in the DCConnect mailbox until the entire host screen has been accepted. If the host crashes, the transactions can be re-read from DCConnect when the host is active again. A special StartTimeout script allows a partially full host screen to be submitted for processing when it becomes clear there are no more DCConnect transactions to be immediately read.

  Max_Xact_Wait( 2000 )       // Wait up to 2 seconds for another
                              // transaction to come in.  If none,
                              // go ahead and run the StartTimeout script
                              // to send the partial screen
  Multi_Release_Mode          // Setting to allow the next transaction
                              // to be read without need to release
                              // the prior one.
 
  ///////////////////////////////////////////////////////////////
  // Process a transaction from a DCT.
  ///////////////////////////////////////////////////////////////
  StartKey( F1 )
 
    UV_Math( UV1, +, 1 )      // Increment transactions-on-screen
                              // counter, which is also used to
                              // determine which row will be used.
                              // Transactions are written to rows
                              // 5 through 19, column 5.
 
    UV_Math( UV2, =, 4 )      // UV2 is used to calculate the row
    UV_Math( UV2, +, UV1 )    // (4 plus the UV1 value )
 
                              // Copy transaction data to the correct
                              // row, no cursor movement, call subroutine
                              // LOCKED if the field is locked.
    Send_To_Host ( TXNDATA, 0, 15, UV2_VALUE, 5, NONE, LOCKED )
 
    If ( UV1 #= "15" )               // If screen is full, send it all to the
      CallSubroutine( Send_Screen )  // host.
 
  EndKey()
 
  ///////////////////////////////////////////////////////////////
  // The StartTimeout script will send any partial screen of data
  // left when the DCTs become inactive, rather than make the
  // transactions sit there waiting for a whole screen.
  ///////////////////////////////////////////////////////////////
  StartTimeout()
 
    If ( UV1 #= "0" ) // UV1 tells how many transactions are
      Goto ALL_DONE   // currently on the host screen.
                      // If 0, no need to send Enter key
 
    CallSubroutine( Send_Screen )
 
  ALL_DONE:
 
  EndTimeout()
 
  ///////////////////////////////////////////////////////////////
  // This routine sends the screen of transactions and
  // calls another routine to check for edit errors; it
  // releases the transactions from DCConnect mailbox and resets the
  // UV1 counter.
  ///////////////////////////////////////////////////////////////
  StartSubroutine( Send_Screen )
 
    Send_To_Host( ENTER )     // Enter will send all transactions on
                              // the screen to the host.
 
 
    UV_Math( UV1, = , 0 )     // Now there are no transactions on the
                              // screen.
 
    Call_Subroutine( Check_&_Correct_Errors) // Write this routine to check
                              // the screen for any edit errors detected
                              // by the host application, and attempt
                              // to correct them, and log the errors.
 
    Release_Xact()            // Releases transactions from DCConnect mailbox
                            // up through the last one read by TC.
  EndSubroutine()
 
  ///////////////////////////////////////////////////////////////
  // This routine handles the case where the host screen is
  // locked/inhibited when trying to copy data to the screen.
  ///////////////////////////////////////////////////////////////
  StartSubroutine( LOCKED )
 
    ... Use Check_Screen, Check_Cursor, If statements, and so
        forth to determine recovery from host problem.  If
        successful at saving logon and data on the screen
        (for example, removing a sys op message from the screen),
        retry sending this transaction and return.
        Otherwise, Cycle the DCConnect Mailbox connection to
        reset DCConnect mailbox pointers to last released transaction,
        reset the UV1 counter, Cycle the host session, and re-logon.
 
  RESEND_TXN:
    Send_To_Host ( TXNDATA, 0, 15, UV2_VALUE, 5, NONE, LOCKED )
    Goto END_LOCKED_SUBR
 
  CYCLE:
    Cycle_Mailbox()
    UV_Math( UV1, =, 0 )
    Cycle_Session( )
    CallSubroutine( Logon_Subr ) // Same commands as used for StartLogon
 
  END_LOCKED_SUBR:
 
  EndSubroutine()

Testing and Debugging Your Scripts Using the Trace Command

If the command Trace is included anywhere in the command script file, then TC creates a trace file (TC2TRCx.nnn) containing a chronological listing of all commands executed. The number to the left of each trace line represents approximately how many milliseconds each command too to execute (including the substantial time taking to actually log this data). This data is very useful for analysing the impact of your SQL statements on execution time (look at the End_SQL / End_SQL2 / End_Select / End_Select2 or Perform... statements). Included is information on the contents of the user variables at entry to the script, updated values of the user variables after each command that can effect them, the transaction record being processed, and the SQL statement and any error messages logged.

Note:

In the user variable listings only non-empty user variables are shown.

If any Trace command is included in the command script file, all execution with that script is in trace mode. To end trace mode, click the On menu item in the Trace pull-down menu. If the Trace command is in the script file, you may want to comment it out so future startups do not come up in trace mode.

The Trace command overrides any No_Display_Execute command in the script file. The expanded execution information is shown in the execution window of the TC window.

Error Log File

All errors encountered by TC are logged into the TC2ERRx.LOG file (where x is the single-character controller ID for the TC session).

Whenever an SQL error is encountered, the SQLSTATE and native code values are logged to the error log as well as the message text returned by DB2 or the ODBC driver. TC will also include the the text of your SQL statement and the data from the transaction that was in progress when the error occurred (data from a remote validation is not logged).

If the SQL error code was one for which you had set a special handling vector with On_Error_Goto, no error logging is done as it is assumed that your recovery code will do what is required.

You can add your own messages to the error log file with the command Log_Error.

Using TC to Generate Reports

Creating Reports from Host Screens

You can create formatted reports from the data on the host screens by utilizing various TC commands. The report can be sent directly to the terminal, written to a disk file, or both. A report on a disk file can be used for audit purposes, processed by another application (see Sending Reports to a DCT), and so forth.

The following example shows how to create a report of the quantity (count) of work items claimed by each worker (as identified by badge number). (This assumes there is some host application capable of showing this result on the screen, given the data provided in a transaction from the DCT).

  StartKey(F2)
 
    // Create a report from host screen listing bin locations
    // where product is stored.  Format the report for printing
    // at the terminal to look like this:
    //
    //    Part Number:  xxxxxxxxxxx
    //    Bin Number     Quantity in Bin
    //    ----------     ---------------
    //    bbbbbbbb       qqqqqqqq
    //    bbbbbbbb       qqqqqqqq
 
    // Take only the first 5 listings on the screen
 
    // Cause any existing report file to be overwritten.
    // The file name will be "REPORT.XYZ", where XYZ is uniquely
    // created from the data collection terminal's physical
    // connection to a communications adapter (X), the line number
    // on that adapter (Y), and the address character of the
    // terminal (Z).
    Clear_UV( UV1 )
    Log_Data(REPORT, UV1, OVERWRITE )
 
    Clear_UV(UV1)
    Clear_UV(UV2)

    Append_UV_Kbd_Data( UV1, "Part Number: ")
    Append_UV_Host_Data( UV1, 5, 25, 7)       // PN on screen
    Append_UV_Kbd_Data( UV1, CRLF)
 
    Append_UV_Kbd_Data( UV1, "Bin Number     Quantity in Bin")
    Append_UV_Kbd_Data( UV1, CRLF)
    Append_UV_Kbd_Data( UV1, "----------     ---------------")
    Append_UV_Kbd_Data( UV1, CRLF)
 
    // Write the report header to disk
    Log_Data ( REPORT, UV1, APPEND )
 
    // Get first 5 lines from host screen, stopping if
    // we hit a blank line (less than 5 available)
    // Bin/Qty data is one lines 10-20 of the host screen,
    // starting in column 10
    // Use
    Clear_UV( UV1 )
    UV_Math ( UV2, =, 10)
 
  LOOP_TOP:
 
    // UV2 will have values 10, 11,...,14, 15
    Append_UV_Host_Data( UV1, UV2_VALUE, 10, 20)
    Append_UV_Kbd_Data( UV1, CRLF)
 
    UV_Math( UV2, +, 1)       // Increment loop counter
 
    If (UV2 #<= "14" )
      Goto LOOP_TOP
 
    // Above loop will put 10 * (20 data + CRLF) = 220
    // characters in UV1, which is less than the 235
    // max for that user variable
    Log_Data ( REPORT, UV1, APPEND )
 
    Release_Xact()
 
  EndKey

Creating Reports from the Database

You can create formatted reports from the database by utilizing various TC commands. The report can be sent directly to the terminal, written to a disk file, or both. A report on a disk file can be used for audit purposes, processed by another application (see Sending Reports to a DCT), and so forth.

The following example shows how to create a report of the quantity (count) of work items claimed by each worker (as identified by badge number) since a time given in a timestamp value in the terminal transaction. The optional format specifier of the Append_UV_Select_Data command is used to maintain a nice columnar alignment in the report.

  StartKey(F2)
 
    // Cause any existing report file to be overwritten.
    // The file name will be "REPORT.XYZ", where XYZ is uniquely
    // created from the data collection terminal's physical
    // connection to a communications adapter (X), the line number
    // on that adapter (Y), and the address character of the
    // terminal (Z).
    Clear_UV( UV1 )
    Log_Data(REPORT, UV1, OVERWRITE )
 
    // Create the SQL statement that counts the number
    // of records resulting after finding only those records
    // created on or after a time specified in the transaction
    // and after grouping those records by the badge number.
    Select_From_DB_Table( LABOR_CLAIMS )
 
    Select_Column( COUNT(*) )
    Select_Column( BADGE )
 
    Select_Where( CLAIM_STAMP, TIMESTAMP, >= , TXNDATA, 0, 12 )
    Select_Group_By( BADGE )
 
    Perform_Select(SQLerror)
 
    // Keep fetching records from the SQL report until
    // the end of the report is reached.
    // Created a formatted user variable with
    // the data from the SQL report, add a carriage return
    // and line feed for readability,
    // append this line to the disk file.
    Fetch_more:
 
    Perform_Fetch(No_more_data_27);
 
    Clear_UV(UV1)
    Clear_UV(UV2)
 
    Append_UV_Kbd_Data( UV1, "BADGE = ")
    Append_UV_Select_Data( UV1, 2, SQLerror, 7 )
    Append_UV_Kbd_Data( UV1, " ; COUNT OF RECORDS = ")
    Append_UV_Select_Data( UV1, 1, SQLerror, 7)
    Append_UV_Kbd_Data( UV1, CRLF)
    Log_Data ( REPORT, UV1, APPEND )
 
    Goto( Fetch_more )
 
  No_more_data_27:
 
    Release_Xact()
 
  EndKey

Sending Reports to a DCT

It is easy to send simple reports to a data collection terminal for printing or displaying. A simple report would have a known and limited size that will fit into the user variable space of the DCT. The terminal clears each user variable that will be used, and then sends the transaction or remote validation request to the TC session through DCConnect. The terminal then watches one of the user variables that serves as a flag indicating that all data from the TC session has now arrived (this user variable may contain useful data, serving as the flag by simply NOT being null). The terminal transaction program uses the TEST and GOTO commands in a tight loop to watch for the flag user variable to be set. When the flag is set, it can proceed to present or print the data from all the user variables, including the flag user variable.

An enhancement to this scenario would be to have a CFR (custom function routine, a user C language extension to the terminal commands) that watches the user variable and watch the clock at the same time to provide a timeout in case the database is inactive or overloaded. In addition, the CFR can verify that when the user variable is eventually set that it contains the proper 'tag' for the transaction that was sent. (see Recommended Design Rules)

More elaborate programming on the DCT can be used to provide for transfer of large amounts of data from the database query into storage on the terminal, and for presentation of this data to the worker (including scrolling and selecting data).

Using One TC Session to Monitor / Control Other TC Sessions and the DCConnect Server

Starting in version 3.1.0d, TC now maintains shared memory that all TC sessions update so that any session can get information about and control other TC sessions. Although any TC session could control / monitor others, it is probably best to have a single TC session serve that function. That session could also act as a web service provider, thus allowing web pages to be set up to control / monitor all TC sessions. The TC commands used to control / monitor other TC sessions are:

• TC_Get_Active_Sessions
• TC_Get_Session_Values
• TC_Send_Session_Command

• Monitor and control terminals:
  • Get_Term_List / Get_Terminal_List
  • Report_Term_State / Report_Terminal_State
  • Report_Term_Version / Report_Terminal_Version
  • Change_Term_State / Change_Terminal_State
  • Load_Term / Load_Terminal
  • Sync_Date_Time
  • Submit_Client_Files
• Monitor and control mailboxes:
  • Get_Mailbox_List
  • Query_Mailbox
  • Clear_Mailbox
• Monitor and control the runtime:
  • Get_DCConnect_Status
  • Shutdown_DCConnect
• Miscellaneous:
  • Get_Application_List
  • Start_Application

  ---

  Script Commands

  This section is organized first as a list of functions, followed by an alphabetical listing of the commands complete with technical reference details.

  Overview of Functions

  Select a function to see its commands.

  • Database Insert Functions
  • Database Query (Select) Functions
  • Database Update Functions
  • Free-Form SQL Functions
  • Miscellaneous Database Functions
  • DCConnect Interface Functions
  • File Logging Functions
  • Flow-of-Control Functions
  • Host Screen Interaction Functions
  • LDAP Functions
  • Operating Mode Switches
  • Response to Terminal Functions
  • TC Control and Monitoring Functions
  • Transaction/Validation/Data Request Sorting Functions
  • User Variable Functions
  • Miscellaneous Functions
  • XML Functions
  • Web Service Functions

  ---

  Database Insert Functions

  Select a command to see technical reference details.

  • Commit_Changes commits the insert changes permanently to the database.
  • Insert_DB_Table indicates the table into which the record will be inserted.
  • Perform_Insert performs the insert operation.
  • Rollback_Changes rollbacks changes made (back-out the work).
  • Setup_Insert_Field sets up data to be inserted into a column.

  ---

  Database Query (Select) Functions

  Select a command to see technical reference details.

  • Append_UV_Select_Data appends data from a column of a SELECT report to a user variable.
  • Close_Cursor closes the report row cursor to allow locks to be removed.
  • Perform_Fetch performs a FETCH of the next row of the SELECT report.
  • Perform_Select performs the SELECT statement created by the other commands.
  • Select_Column chooses another column or column function to be included in the SELECT report.
  • Select_From_DB_Table indicates which table the query will run against.
  • Select_Group_By establishes optional grouping phrase of the SELECT statement.
  • Select_Having establishes optional SELECT HAVING phrase of the SELECT statement.
  • Select_Order_By establishes optional ordering phrase of the SELECT statement.
  • Select_Where establishes optional SELECT WHERE phrase of the SELECT statement.

  ---

  Database Update Functions

  Select a command to see technical reference details.

  • Commit_Changes commits the changes permanently to the database.
  • Perform_Update performs the update operation.
  • Rollback_Changes rollbacks changes made (back-out the work).
  • Setup_Update_Field sets up data to be updated for a column.
  • Update_DB_Table indicates the table that should have a record(s) updated.
  • Update_Where establishes the row conditions necessary to require updating.

  ---

  DCConnect Interface Functions

  Select a command to see technical reference details.

  • Clear_Mailbox can be used to clear all transactions from a specific DCConnect mailbox.
  • Change_Term_State can be used to change the service state (in service / out of service) or polling stated (polled / not polled) of a particular terminal.
  • Cycle_DCC/2_Export / Cycle_Mailbox closes and reopens the DCConnect mailbox so that transactions that have already been read but not released are read again.
  • Get_Application_List gets the list of valid applications in the DCConnect configuration.
  • Get_DCConnect_Status returns the current status of the DCConnect Server.
  • Get_Job_List gets the list of valid jobs in the DCConnect configuration.
  • Get_Mailbox_List gets the list of valid mailboxes in the DCConnect configuration.
  • Get_Term_List gets the list of valid terminals in the DCConnect configuration. The list can also be limited to a specific job.
  • Initiate_Term_Event starts a transaction program (terminal event) on any terminal.
  • Load_Term / Load_Terminal initiate a partial or full download of a data collection terminal.
  • Make_Data_Request allows a data request to be made of another application. The reply can than be processed.
  • Query_Mailbox can be used to get the following information about a DCConnect mailbox: number of transactions to be read, to be release, indication whether mailbox is active, its capacity and the name of the physical transaction log file.
  • Release_Xact releases the current transaction from the DCConnect mailbox.
  • Report_Term_State / Report_Terminal_State can be used to report the service state (in service / out of service), polling stated (polled / not polled) of a particular terminal. It also returns the current operation state (e.g. Not Responding or Downloading).
  • Report_Term_Version / Report_Terminal_Version can be used to report the version of the DCConnect Client or firmware of a particular terminal.
  • Shutdown_DCConnect used to shut down the DCConnect Server.
  • Start_Application starts an application that is part of the DCConnect configuration. (Get_Application_List can be used to get a list of those applications).
  • Submit_Client_Files submits a set of one more DCConnect Client files to replace files for one or more terminals.
  • Submit_Validation submits a data file to DCConnect for conversion to a DCConnect data validation file.
  • Sync_Date_Time sets the date/time of the DCConnect Server machine and/or updates the terminals with the current date/time of the server.
  • Write_Xact / Write_Xact2x write data to the DCConnect mailbox for import by another DCConnect application.

  ---

  Free-Form SQL Functions

  Select a command to see technical reference details.

  • Begin_Select / Begin_Select2 begins a free-form SQL statement section that will be treated like a select statement intended to return a result set.
  • Begin_SQL / Begin_SQL2 begins a free-form SQL statement section.
  • Commit_Changes commits the changes permanently to the database.
  • End_Select / End_Select2 ends a free-form SQL select statement, prepares and executes the statement.
  • End_SQL / End_SQL2 ends a free-form SQL statement, prepares and executes the statement.
  • Format_UV formats a TC user variable so it is in the proper form to fit the database table column type.
  • Rollback_Changes rollbacks changes made (back out the work).

  ---

  Miscellaneous Database Functions

  Select a command to see technical reference details.

  • Database / DB specifies the name of the database(s) to which TC will connect/
  • DBUserid specifies the user ID to be used when connecting to the database.
  • DBPassword specifies the password to be used with the user ID when connecting to the database.
  • DBEncryptedPW, a more secure alternative for DBPassword, specifies the password, encrypted, to be used with the user ID when connecting to the database. The utility TCENCRYPT.exe, is used to generate the encrypted password given a user provided key.
  • Database / DB is a synonym for Database
  • DB_Null_Empty specifies that NULL values selected from a database table are stored in user variables as empty strings.
  • DB_Null_Space specifies that NULL values selected from a database table are stored in user variables as a single space character.
  • DB_Null_Text specifies that NULL values selected from a database table are stored in user variables as the text '<NULL>' .
  • Deadlock_Timeout can be used to change the time that TC allows and ODBC database operation to take before assuming a deadlock has occurred and shuts down. The default is 1 minute.
  • Define_On_Error_String allows you to define for use in On_Error_Goto commands, On Error strings that are not already defined in any of the RC_*.INI files.
  • Get_DBType gets the underlying database type (e.g. ORACLE, DB2, SQL SERVER) for an ODBC datasource alias.
  • Run_Without_Connect allows running without a database connection even though a database name has been specified.
  • SQL_Buffer_Size can be used to increase the size of the buffer used for building SQL commands. The default size is 4000 bytes.

  ---

  File Logging Functions

  Select a command to see technical reference details.

  • Log_Data logs the contents of a TC user variable to a disk file of your choice.
  • Log_Error logs your own error information to the error log file.
  • Log_Xact logs the current transaction to the disk file of your choice.

  ---

  Flow-of-Control Functions

  Select a command to see technical reference details.

  • Call calls a subroutine with a variable number of parameters
  • Call_Subroutine calls a subroutine.
  • Check_Color looks for the specified color to be used in a specific row and column.
  • Check_Cursor looks for the cursor to be located in a specific row and column.
  • Check_Highlight looks for the text highlighting to be used in a specific row and column.
  • Check_MW looks at the AS/400 message waiting indicator and branches based on its settings.
  • Check_II looks at the AS/400 input inhibited indicator and branches based on its condition. When the AS/400 keyboard is locked you will find that either the Busy or Input Inhibited indicator is active.
  • Check_Busy looks at the AS/400 Busy indicator and branches based on its condition. When the AS/400 keyboard is locked you will find that either the Busy or Input Inhibited indicator is active.
  • Check_Screen looks for specific text on the screen and branch if not found.
  • Define_On_Error_String allows you to define for use in On_Error_Goto commands, On Error strings that are not already defined in any of the RC_*.INI files.
  • Delay delays for some number of milliseconds (1/1000 ths) or until OK is pressed.
  • EndSub / EndSubroutine ends a subroutine's script definition.
  • Goto goes to a labeled line of the script and execute from there.
  • If executes the next step(s) conditionally based on a comparison of one or more sets of information.
  • Label labels a line of the script.
  • LDAP_AdminBind Establish an administrator connection to an LDAP server.
  • LDAP_AdminUnbind Disconnect the administrator connection to an LDAP server.
  • LDAP_ChangePassword Given a user ID, and blowfish encrypted new and old passwords, send the credentials to the LDAP server to update the password.
  • LDAP_Encrypt Encrypt a string of text using the blowfish encryption algorithm.
  • LDAP_Search Perform a search against the LDAP server.
  • LDAP_ValidateUser Given a user ID and blowfish encrypted password, send the credentials to the LDAP server for validation. Optionally retrieve attribute values for that user.
  • Make_Data_Request allows a data request to be made of another application. The reply can than be processed.
  • On_Error_Goto branches to a set of labels based on a set of SQL errors or the generic SESSION (host emulator session) error.
  • Quit_Subroutines quits from any stacked subroutines. Call this when you branch from a subroutine back to the main level of the script without allowing the end of the subroutine(s) to run.
  • Sub starts definition of a subroutine script with passed parameters.
  • StartSubroutine starts definition of a subroutine script with no parameters being passed.
  • Wait_Until_Unlocked waits for the host screen to unlock, branching to a label if not done within one minute.
  • While (Do...While) repeats execution of a set of steps while a comparison of one or more sets of information results in a true condition.
  • Xact_Age branches to a label based on the age of the current transaction record.
  • XML_CopyElement copies the element and any children from the current position in the source XML message to the current position in the target XML message.
  • XML_EnterElement enters an element under the current position.
  • XML_GetField2 Get the data stored in a child node.
  • XML_Parse parses an XML string and returns a handle which can be used in any other XML function.
  • XML_Send sends the XML message and waits for a return message. Nothing is assumed about the return message format.
  • XML_SendBOD sends the XML message and waits for a return message. The return message is assumed to be a BOD as well.

  ---

  Host Screen Interaction Functions

  Select a command to see technical reference details.

  • Append_UV_Host_Data appends to a user variable a string that is copied from the host screen.
  • Capture_Screen copies to a (large) user variable the entire host screen, putting a carriage return/line feed at the end of each row. =to a user variable a string that is copied from the host screen.
  • Check_Color looks for a specified screen foreground or background color to be located in a specific row and column, and processes accordingly.
  • Check_Cursor looks for the cursor to be located in a specific row and column and processes accordingly.
  • Check_Highlight looks for a specified screen highlighting attribute to be located in a specific row and column, and processes it accordingly.
  • Check_MW looks at the AS/400 message waiting indicator and can branch based on its setting. waiting indicator and branches based on its settings.
  • Check_II looks at the AS/400 input inhibited indicator and branches based on its condition. When the AS/400 keyboard is locked you will find that either the Busy or Input Inhibited indicator is active.
  • Check_Busy looks at the AS/400 Busy indicator and branches based on its condition. When the AS/400 keyboard is locked you will find that either the Busy or Input Inhibited indicator is active.
  • Check_Screen looks for specific text on the screen and processes accordingly.
  • Communication_Connect performs the same function with IBM Personal Communication's as manually selecting Communications-Connect from the PCOMM menu bar.
  • Communication_Disconnect performs the same function with IBM Personal Communication's as manually selecting Communications-Disconnect from the PCOMM menu bar.
  • Cycle_Session stops and re-starts the host terminal emulation session.
  • Get_Cursor gets the cursor position from the host screen.
  • Screen_Width sets the number of columns to be expected on the host screen.
  • Send_Host_Kbd_Data sends keystrokes or a string to the host screen.
  • Send_Host_UV_Data sends all of a user variable to the host screen.
  • Send_Host_Data_Part sends all or part of any allowed data part to the host screen. (Originally called Send_Host_Xact_Data.)
  • Send_Host_Xact_Data same as Send_Host_Data_Part above.
  • Send_Term_Data sends a string from the host screen directly to the current terminal.
  • Send_To_Host sends data to the host screen and is the general, most powerful, and fastest method. Data can be constants, control keys, or data from the defined data parts (transaction data, user variable data, and so forth).
  • Session_Connect connects the TC session to its designated host emulator window.
  • Set_Cursor sets the cursor position on the host screen.
  • Set_Emulator_Window sets the host emulator window to minimized, maximized, restored, active, or inactive.
  • Wait_Until_Unlocked waits for the host screen to unlock, branching to a label if not done within one minute.
  • WorkStation_Profile specifies the Personal Communications emulator window Workstation Profile to be used in case TC finds it needs to start the emulator session.

  ---

  LDAP Functions

  • LDAP_AdminBind Establish an administrator connection to an LDAP server.
  • LDAP_AdminUnbind Disconnect the administrator connection to an LDAP server.
  • LDAP_ChangePassword Given a user ID, and blowfish encrypted new and old passwords, send the credentials to the LDAP server to update the password.
  • LDAP_Encrypt Encrypt a string of text using the blowfish encryption algorithm.
  • LDAP_Search Perform a search against the LDAP server.
  • LDAP_ValidateUser Given a user ID and blowfish encrypted password, send the credentials to the LDAP server for validation. Optionally retrieve attribute values for that user.

  ---

  Operating Mode Switches

  Select a command to see technical reference details.

  • Application specifies the application name to use in the case validation requests or data requests are being processed.
  • Close_When_Complete closes the window when TC completes.
  • Cntlr specifies the single character controller ID to use.
  • Current_Dir changes the current directory that TC is working in.
  • Dont_Maintain_Window_Position tells TC not to keep track of the size and position of the TC session. (As of 3.0.8d release, TC automatically maintains its window size and position based on the controller ID).
  • DP_Is_Comma sets the decimal point as used in the UV_Math function to be a comma instead of a period.
  • Mailbox / Export specifies the name of the DCConnect mailbox to read transactions from. It can also be used to specify that the script handles validation requests or data requests instead of transactions.
  • Max_Xact_Wait specifies the maximum time that TC waits for a transaction/request from DCConnect before it runs the StartTimeout script.
  • Multi_Release_Mode configures for multiple transaction release mode.
  • No_Display_Execute specifies that every step in the execution should not be displayed on the screen.
  • No_Terminate_From_DCConnect tells TC not to terminate when calls to DCConnect APis indicate that the DCConnect Server is shutting down or is not running.
  • Password sets an operator password which must be used to shut down a session or change certain operational modes.
  • Reenable_Trace_Via_Restart is used to specify that the TC session should use a restart (when idle) as the mechanism for resuming tracing, if tracing has to be suspended because script execution has been slowed on an overloaded/busy Windows system. This creates a fresh connection with the tracing process.
  • Resize_Both_Panes tells TC to resize both the Execution pane and Messages pane when the TC window is resized. This is also the default behavior if none of the Resize_* commands are used in the scripts.
  • Resize_Execution_Pane_Only tells TC to resize only the Execution pane and not the Messages pane when the TC window is resized. This used to be the default behavior of TC. But as of the 3.0.8d release in September 2012, the default behavior was changed to resize both panes together.
  • Resize_Messages_Pane_Only tells TC to resize only the Messages pane and not the Execution pane when the TC window is resized. As of the 3.0.8d release in September 2012, the default behavior was changed to resize both panes together.
  • Run_Without_Session allows running without a host screen connection even though a session short name has been specified.
  • Session specifies the short session to use if logging on to a host system.
  • Show_Thread_Messages tells TC to show messages about threads starting and stopping.
  • Silent turns off any warning beeps that might be generated.
  • Trace turns on execution trace mode for debugging purposes. A trace log is generated as a result.
  • Trace_Delay_Limit used to configure detection of script execution slowness due to tracing on an overloaded/busy Windows system.
  • Trace_Size used on Windows to override the default number and size of trace files that are generated by TCTRACE on behalf of the specific TC sessions that use the command.
  • Use_Adjusted_Xact_Time tells TC to use the adjusted date and time fields from the transaction record for the original transaction date and time data parts (e.g. YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, ...) rather than the terminal date and time fields in the transaction record. You can still access the terminal date and time fields of the transaction record using the date and time data parts with the TERM prefix (e.g. TERMYEAR, TERMMONTH, TERMDAY, ...).
  • WS_DisplayExecutePopups specifies that popups associated with certain web service commands (e.g. WS_SendRequest, WS_SendResponse) should be shown when Display mode is in effect.
  • XML_Sender specifies the dynamic link library (DLL) and function to use when sending XML messages. Use a colon to separate the DLL name and function name (ie. DLL_Name:Function_Name).

  ---

  Response to Terminal Functions

  Select a command to see technical reference details.

  • Reply_To_Data_Request sends the contents of a user variable to the originator of a data request.
  • Forward_Data_Request specifies that the active data request should be forwarded to another application.
  • Send_Term_Data sends to a user variable on the current terminal a copy of some part of the host screen.
  • Send_Term_IResp sends the current terminal an interactive response
  • Send_Term_UV_Data sends to a user variable on a data collection terminal a copy of the data in a TC user variable.
  • Send_Term_VResp sends the current terminal a remote validation response.

  ---

  TC Control and Monitoring Functions

  Select a command to see technical reference details.

  • TC_Get_Active_Sessions Get a list of controller IDs for all the TC sessions that are active.
  • TC_Get_Session_Values Get the current value of one or more attributes for a particular TC session.
  • TC_Send_Session_Command Send a command to a particular TC session.

  ---

  Transaction/Validation/Data Request Sorting Functions

  Select a command to see technical reference details.

  • EndFunctionGroup / EndCluster ends StartFunctionGroup block containing one or more StartKey / EndKey scripts.
  • EndInterval ends the StartInterval script.
  • EndKey ends a StartKey script.
  • EndMatch ends a StartMatch script.
  • EndTime ends a StartTime script.
  • EndTimeout ends the StartTimeout script.
  • EndVal ends a StartVal script.
  • StartFunctionGroup / StartCluster starts a block of StartKey / EndKey scripts which correlate to a specific DCConnect function group.
  • StartInterval starts a script that is run at a certain time interval which is specified in the StartInterval command.
  • StartKey starts a script that is to be run when a transactions is received with a particular key ID. If contained within a StartFunctionGroup block, the specified function group must also match the function group from the transaction.
  • StartMatch starts a script that is to be run when a portion of the data from an incoming transaction/request matches a particular string. The content and length of that string is specified in the StartMatch command.
  • StartTime starts a script that is to be run at a specific time of the day. The StartTime command specifies the specific hour-minute-second at which the script should be run.
  • StartTimeout starts script that is to be run when no transaction has been received within a specific timeout period. That timeout period is specified by the Max_Xact_Wait command.
  • StartVal starts a script that is to be run when a validation request is received and that request specifies the same validation file that is specified in the StartVal command.

  ---

  User Variable Functions

  Select a command to see technical reference details.

  • Append_UV_Ctrl_ID appends to a user variable the controller ID character specified on the command line or in a script.
  • Append_UV_File_Data Reads data from a flat file and appends it to a user variable.
  • Append_UV_Host_Data appends to a user variable a string that is copied from the host screen.
  • Append_UV_Kbd_Data / Append appends a user variable a constant string.
  • Append_UV_Select_Data appends to a user variable data from a column of a SELECT report.
  • Append_UV_Seq_Num appends to a user variable from the four digit sequence number maintained by the TC session.
  • Append_UV_UV appends to a user variable from another.
  • Append_UV_Data_Part appends to a user variable all or part of any allowed data part (originally called Append_UV_Xact_Data).
  • Append_UV_Xact_Data same as Append_UV_Data_Part above.
  • Begin_UV - End_UV Defines the boundaries of a formatted text user variable area. Within these boundaries you specify fixed text and user variable/transaction field references and TC builds it all into a single string and sets a target user variable with the result.
  • Clear_UV clears a user variable
  • Declare allows you to define a local user variable
  • Define_Large_UV_Size allows you to redefine the size of large user variables - up to 64Kb instead of the default of 16kb.
  • Define_UVs allows you to define how many user variables are available and how many of those are of the large size.
  • Dump_UVs can be used when tracing is active to dump the contents of all non-empty user variables, global and local, to the trace.
  • Format_UV formats a user variable for use in a database field, to a specific size or style, or adds/removes/replaces characters or strings.
  • Get_Application_List gets the list of valid applications in the DCConnect configuration.
  • Get_Cursor gets the current cursor position and store the row and column in two specified user variables.
  • Get_Job_List gets the list of valid jobs in the DCConnect configuration.
  • Get_Length gets the length of some data from the current transaction record or of a user variable and stores that length in a user variable.
  • Get_Mailbox_List gets the list of valid mailboxes in the DCConnect configuration.
  • Get_Term_List gets the list of valid terminals in the DCConnect configuration. The list can also be limited to a specific job.
  • Get_Term_UV_Data gets the value of a DCT user variable and copies it to a TC user variable.
  • Load_UVs loads from disk the previously saved contents of UV1-20 for the terminal that originated the current transaction/validation request.
  • Name_UV allows you to assign a meaningful name to a user variable.
  • Parse_UV can be used to split a user variable into parts based on the location of a delimiter character or string.
  • Save_UVs saves the current contents of UV1 through UV20 to a disk file for the terminal that originated the current transaction/validation request.
  • Send_Host_UV_Data sends all of a user variable to the host screen.
  • Send_Term_UV_Data sends to a user variable on the current terminal a copy of the data in a TC user variable.
  • Send_To_Host general, most powerful, and fastest method to send data to the host screen. Data may be constants, control keys, or data from a user variable to a host screen.
  • Set_UV_... provides the same function as the corresponding Append_UV_... function except that the user variable is cleared first. The Set command has the same correlation to the Append command.
  • UV_Math performs arithmetic functions on the user variable's value.
  • Write_Xact / Write_Xact2x write a transaction to the DCConnect mailbox, with data coming from a user variable or other data part.

  ---

  Web Service Functions

  Select a command to see technical reference details.

  • WS_AddAttribute Add an attribute to the current web service XML document node. This can be used to define namespaces at the root level.
  • WS_AddHTTPHeader Add an HTTP header for the specified header key and value in the current web service request.
  • WS_Cleanup / WSCleanup Cleans-up/destroys the storage dedicated to a web service request or response.
  • WS_CreateElement / CreateWSElement Creates a new, empty XML element under the current node in the web service document.
  • WS_CreateRequest / CreateWSRequest Creates a new, outgoing web service request that will be sent to a service provider endpoint.
  • WS_CreateResponse / CreateWSResponse Creates a new, outgoing web service response for use in replying to an incoming web service request that this TC session provides.
  • WS_DefineNamespace Define a namespace URI and the prefix by which you will refer to that namespace.
  • WS_NamespacePush Push the current set of namespaces into a level and start a fresh level. Use this to build subroutines that add their own XML content without being aware of what namespace prefixes are being used by the higher calling levels.
  • WS_NamespacePush Pop the prior set of namespaces into the current namespace manager level. Use this to build subroutines that add their own XML content without being aware of what namespace prefixes are being used by the higher calling levels.
  • WS_EnterElement / WS_EnterElementXPATH / EnterWSElement Command sets an element name to be the current node for navigation (e.g. finding or creating child nodes).
  • WS_GetAttribute Get the value of a named attribute from the current node of a web service XML document
  • WS_GetElement / WS_GetElementXPATH / GetWSElement Gets the value of an element in an XML document that has been received in an incoming web service request, or has been received in a response from a call to a web service endpoint.
  • WS_GetLastErrorText Gets the text of the last error that occurred with any of the Web Service commands.
  • WS_LeaveElement / LeaveWSElement Leaves the current node and moves up to the parent node to be the current node for navigation (e.g. finding or creating child nodes).
  • WS_SendRequest / SendWSRequest Sends an outgoing web service request to a service provider endpoint.
  • WS_SendResponse / SendWSResponse Sends an outgoing web service response as a reply to an incoming web service request.
  • WS_SetElement / WS_SetElementXPATH / SetWSElement Sets the value of an element in an XML document that is being created for transmission to a web service endpoint.
  • WS_SetHTTPBody Set the HTTP body of a web service request when it is not an XML document - such as when the request format is JSON.
  • WS_SetHTTPParameter Set an HTTP header parameter in the current web service request. This is for reserved request header keys: ACCEPT, CONTENT_TYPE, METHOD and REQUEST_TYPE.

  XML Functions

  Select a command to see technical reference details.

  • XML_AddAttribute adds an attribute to the element at the current position.
  • XML_AddField Add a child node and set the value in the node.
  • XML_Cleanup Free storage associates with an XML message handle.
  • XML_Configure used to dynamically configure transmission of an XML message.
  • XML_CopyElement copies the element and any children from the current position in the source XML message to the current position in the target XML message.
  • XML_Create creates an empy XML message
  • XML_CreateBOD Creates an XML message and inserts the BOD header information.
  • XML_CreateElement Create an XML element under the current position.
  • XML_EnterElement Enter an XML element under the current position.
  • XML_GetField Get the data stored in a child node.
  • XML_LeaveElement Move the current position up to the parent of the current position.
  • XML_LoadLoggingParameters Load the XML logging parameters such as LOGFILE, LOGCOUNT or LOGLEVEL from a file.
  • XML_Parse parses an XML string and returns a handle which can be used in any other XML function.
  • XML_Send sends the XML message and waits for a return message. Nothing is assumed about the return message format.
  • XML_SendBOD sends the XML message and waits for a return message. The return message is assumed to be a BOD as well.
  • XML_Sender sets the function which should be called to transmit an XML message to another application. The specified function will be called by XML_Send or XML_SendBOD.
  • XML_SetField Set the data in a child node.
  • XML_ToFile takes the XML structure from the specified UV and generates a 'serialized' string from it and then writes it to the specified file.
  • XML_ToString takes the XML structure from the specified UV and generates a 'serialized' string from it, storing that in the target variable.

  ---

  Miscellaneous Functions

  Select a command to see technical reference details.

  • //Comment adds non-executed commentary. to your script file
  • Define_On_Error_String allows you to define for use in On_Error_Goto commands, On Error strings that are not already defined in any of the RC_*.INI files.
  • Delay delays for some number of milliseconds (1/1000ths) or until OK is pressed.
  • Description sets a text description that is shown on the TC window.
  • End / End_TC ends execution of TC and returns to the operating system.
  • Imbed includes another text file inline as your script file is being compiled.
  • EndLogon identifies the script action used for host/database logon whenever TC starts.
  • Restart_TC ends execution of TC and spawns a new, replacement TC process.
  • Set_Xact_Time_Of_Origin sets the time and date of the transaction just received affecting the Xact_Age command and the data parts XACT_AGE, YEAR, MONTH, DAY, ... The transaction time and date is set from a user variable.
  • StartLogoff and EndLogoff identifies the script action used for host/database logoff whenever TC ends.
  • System executes any operating system command, or runs an external command file.
  • Write_To_Event_Log is used to log a message to the Windows event log.

  ---

  ---

  Command Reference

  The reference information for each command begins with a description of the command syntax and any alternative forms you can use. For example:

    Append_UV_Select_Data( UV, SELECT_ITEM )
    Append_UV_Select_Data( UV, SELECT_ITEM, ERR_LABEL )
    Append_UV_Select_Data( UV, SELECT_ITEM, ERR_LABEL, FORMAT)
  

  shows that you have 3 alternate formats available for the Append_UV_Select_Data command. The formats often start with a simple form of the command and then progress to include more advanced optional functions. In this example, the first, simplest form does no special error handling and accepts the data in a default format. The second form adds a label name that indicates what steps to execute if an error is found during the processing of the command. The final form adds data on what format you want the data to be in when completed. Notice that the style:

    Append_UV_Select_Data( UV, SELECT_ITEM, FORMAT)
  

  is not listed in the syntax reference. This omission indicates you must specify an error label if you want to take advantage of the FORMAT function. This is the only way the command compiler expects to find a FORMAT parameter. If you omit the ERR_LABEL and attempt to use the FORMAT parameter, the compiler will interpret the format data as a label name, and this will probably result in a "Label not found" error at the end of the compile.

  Note: Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "15", "ShippingMailbox", and so forth) or as the current value of a TC user variable by using the user variable's name or the notation UVn, where n ranges from one to 250 or the maximum defined by Define_UVs.

  Append_UV_Ctrl_ID

    Append_UV_Ctrl_Id( UV )
  

  Append to the end of a TC user variable from the controller ID specified when TC was started from the command line or command file.

  UV	The TC user variable; not to be confused with the user variables resident in the data collection terminals.

  Example:
   
    // Append controller ID to UV 1
    Append_UV_Ctrl_Id ( UV1 )
  

  Append_UV_Cntlr_ID

    Append_UV_Cntlr_Id( UV )
  

  Append to the end of a TC user variable from the controller ID specified when TC was started from the command line or command file. This command is an alias for the the Append_UV_Ctrl_ID command and provides the same function.

  UV	The TC user variable; not to be confused with the user variables resident in the data collection terminals.

  Example:
   
    // Append controller ID to UV 1
    Append_UV_Cntlr_Id ( UV1 )
  

  Append_UV_Data_Part

    Append_UV_Data_Part( UV, DATA_PART, START*, LENGTH* )
  

  This function is synonymous with Append_UV_Xact_Data.

  Append to a TC user variable from data in the incoming transaction record or from data in another user variable or any valid data part.

  Note: Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a TC user variable by using the user variable's name or the notation UVn, where n ranges from one to 250 or the maximum defined by Define_UVs.

  UV	A TC user variable; not to be confused with the user variables resident in the data collection terminals.
  DATA_PART	This specifies one of various predefined parts of the terminal transaction or other information that becomes part of the data appended to the target user variable. The predefined parts are listed in Data Parts. The data parts that are valid vary depending on whether the TC session is currently running in transaction, validation or data request mode.
  START*	The starting position within the selected data part. 0 is the beginning of the data. As of release 3.0.8d, this parameter and the following parameter are optional. If only one of these two optional parameters is give, it is assumed to be the START position.
  LENGTH*	The length of data to use from the data part, starting at the START position. Refer to Data Parts for the meaning of a 0 length for a given data part. It may be ignored, it may mean return no data or it may mean take all data from the START position.

  Examples:
   
    // append all of UV2 to UV1
    Append_UV_Data_Part ( UV1, UV2, 0, 0)
   
    // append 10 characters of UV2, starting at offset 5, to UV1
    Append_UV_Data_Part ( UV1, UV2, 5, 10)
   
    // append the transaction timestamp to UV30
    Append_UV_Data_Part ( UV30, TIMESTAMP, 0, 12)
  

  Append_UV_File_Data

    Append_UV_File_Data( uvRC, uvTarget, Length*, uvDelimiter )
    Append_UV_File_Data( uvRC, uvTarget, Length* )
  

  Read from and parse the current open data file and append this data to a target user variable. The file pointer is left positioned at the end of this read, ready for the next read.

  This command cannot overflow a user variable's string space. Once the user variable is full the command will return uvRC = 0 (except if nothing could be read at all due to a full target user variable; in this case, uvRC = 3.)

  uvRC	The user variable you specify for uvRC shows the return code from the Append_UV_File_Data call. A value of 0 indicate success. Any other value indicate failure: 0 NO ERROR 2 ERROR END OF FILE -- NOTHING WAS READ 3 ERROR UV FULL -- NOTHING READ 5 ERROR ACCESS DENIED 6 ERROR_INVALID_HANDLE -- CALL IBM 26 ERROR_NOT_DOS_DISK 33 ERROR_LOCK_VIOLATION 109 ERROR_BROKEN_PIPE 234 ERROR_MORE_DATA
  uvTarget	The destination user variable for the data from the flat file. Set_UV_File_Data will cause this user variable to be cleared first.
  Length*	The maximum length of data to read. Specify 0 to read as much data as will fit in the user variable (up to the end of the file or to an optional specified delimiter). The length may be specified by the current contents of a user variable.
  uvDelimiter	A user variable which contains a string of one or more character which constitutes a delimiter which stops the read of file data for this command. The delimiter may be, for example, a single comma, a CRLF two-character sequence, or any other series of characters. The delimiter is not returned in the target user variable (e.g. it is stripped off) and the file pointer advances past the delimiter. This parameter is optional. If not specified, the Length parameter, the size of the file, and the space in the user variable determine how much data is read.

  Examples:
   
    // Example 1
    // Read as much of the file as will fit
    // in one user variable, with no regard
    // for delimiters
   
    Open_File_Data( UV1, "Badges.dat" )
    Set_UV_File_Data ( UV1, UV2, 0 )
    Close_File_Data()
   
   
   
   
    // Example 2
    // Read up to the next CRLF in the file
    // to obtain each badge number.
   
    Set_UV_Kbd_Data( uvDelim, CRLF )
   
    Open_File_Data( UV1, "Badges.dat" )
   
    Do
     {
      Set_UV_File_Data ( UV1, UV2, 0, uvDelim )
      If ( UV1 #== "0" )
       {
        ... Update/Insert database table
       }
     }
    While ( UV1 #== "0" )
   
    Close_File_Data()
   
   
   
   
    // Example 3
    // Read the file 10 characters at a time
    // with no regard for delimiters.
   
    Open_File_Data( UV1, "Badges.dat" )
    Do
     {
      Set_UV_File_Data ( UV1, UV2, 10 )
      If ( UV1 #== "0" )
       {
        ... do something
       }
     }
    While ( UV1 #== "0" )
    Close_File_Data()
   
   
   
    // Example 4
    // Read to the next delimiter, but
    // limit the read length to 4 characters.
    // Note that the subsequent reads could
    // return 0-4 characters, depending on
    // where the delimiter lay.
   
    Open_File_Data( UV1, "Badges.dat" )
    Do
     {
      Set_UV_File_Data ( UV1, UV2, 4, uvDelim )
      If ( UV1 #== "0" )
       {
        ... Do something
       }
     }
    While ( UV1 #== "0" )
    Close_File_Data()
   
   
   
    // Example 5
    // A flat file contains 3 fields on each line.
    // The lines are terminated with CRLF.  The
    // 3 fields are fixed-length:
    //  1) PO Number:   Start at 0 for 10
    //  2) Line Item:   Start at 12 for 5
    //  3) Part Number: Start at 19 for 8
    //
    // Read the entire line to the CRLF delimiter,
    // then split the line into fixed lengths.
   
    Name_UV( UV1, uvDelim)
    Name_UV( UV2, uvRC)
    Name_UV( UV3, uvLine)
    Name_UV( UV4, uvPONum)
    Name_UV( UV5, uvPOItem)
    Name_UV( UV6, uvPOPartNum)
    Set_UV_Kbd_Data( uvDelim, CRLF )
   
    Open_File_Data( UV1, "purreqs.dat" )
   
     // Keep reading the unknown number of lines of flat
     // file until we hit end or some serious error
    Do
     {
       // Read the entire line to the CRLF delimiter,
      Set_UV_File_Data ( uvRC, uvLine, 0, uvDelim )
      If ( uvRC #== "0" )
       {
          // Got a line. Split the line into fixed lengths.
         Set_UV_Data_Part( uvPONum, uvLine, 0, 10)
         Set_UV_Data_Part( uvPOItem, uvLine, 12, 5)
         Set_UV_Data_Part( uvPOPartNum, uvLine, 19, 8)
   
        ... Update/Insert database table
       }
      Else
       {
         If ( uvRC #!= "2")
          {
            // Not a normal error
            Append_UV_Kbd_Data( uvRC, " was error rec'd while reading data file")
            Log_Error( uvRC )
          }
       }
     }
    While ( UV1 #== "0" )
   
    Close_File_Data()
   
  

  Append_UV_Host_Data

    Append_UV_Host_Data( UV, ROW*, COL*, LENGTH* )
  

  Append to the end of a TC user variable from a string located on the host session display. The upper-left corner of the display is row 1, column 1. See Screen_Width if your host session runs in other than 80-column mode.

  Note:

  Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a TC user variable by using the user variable's name or the notation UVn, where n ranges from 1 to 250 or the maximum defined by Define_UVs.

  UV	A TC user variable; not to be confused with the user variables resident in the data collection terminals.
  ROW*	Host display row number.
  COL*	Host display column number.
  LENGTH*	The length of the data to copy.

  Example:
   
    // Append to user variable 1 from data starting at row 12, column 25, for
    // a length of 10 characters
    Append_UV_Host_Data( UV1, 12, 25, 10 )
  

  Append_UV_Kbd_Data / Append

    Append_UV_Kbd_Data( UV, "String" )
    Append_UV_Kbd_Data( UV, NumericConstant )
    Append_UV_Kbd_Data( UV, CTRL_CODE )
    Append_UV_Kbd_Data( UV, %EnvironmentVariable% )
  
    Append( UV, "String" )
    Append( UV, NumericConstant )
    Append( UV, CTRL_CODE )
    Append( UV, %EnvironmentVariable% )
  

  Append to a TC user variable from a literal string of data you key into the command file, a numeric constant or from one of a set of predefined control characters or from an environment variable. from a user variable. The literal string must be in double-quotes.

  Append was added as a synonym for Append_UV_Kbd_Data in version 3.1.0e.

  UV	A TC user variable; not to be confused with the user variables resident in the data collection terminals.
  "String"	Any string enclosed in double-quote characters. If the string contains environment variables (denoted by starting and ending percent signs (%) these environment variables will not be resolved by TC; they will be left as they are found.
  NumericConstant	Numeric constants do not have to be enclosed in double quotes and can be any base 10 number, optionally having a leading negative sign and optionally having a decimal point.
  CTRL_CODE	Append control character(s) to the user variable. Valid control code definitions are: CTRL_CODE Description Hex Value --------- ----------- --------- SOH Start of heading 01h STX Start of text 02h ETX End of text 03h EOT End of transmission 04h ENQ Enquiry 05h ACK Acknowledge 06h BEL Bell 07h BS Backspace 08h HT Horizontal tab 09h LF Line feed 0Ah VT Vertical tab 0Bh FF Form Feed (page feed) 0Ch CR Carriage return 0Dh SO Shift out 0Eh SI Shift in (condensed) 0Fh DLE Data link escape 10h DC1 Device control 1 11h DC2 Device control 2 12h DC3 Device control 3 13h DC4 Device control 4 14h NAK Negative Acknowledgement 15h SYN Synchronize 16h ETB End transmitted block 17h CAN Cancel 18h EM End of medium 19h SUB Substitute 1Ah ESC Escape 1Bh FS File separator 1Ch GS Group separator 1Dh RS Record separator 1Eh US Unit separator 1Fh CRLF CR and LF together 0D0Ah COMMA The character (,) 2Ch DOUBLE_QUOTE The character (") 22h
  %EnvironmentVariable%	If the second parameter starts and ends with percent signs (%), TC assumes it specifies one or more environment variables to be resolved. TC resolves these environment variables at compile time. If it is unable to, a compile error results.

  This option is useful when using the Log_Data command to create a report file.

  Examples:
   
    // Last line of report, then add carriage return/line feed
    // and feed sheet of paper on printer.
    Append_UV_Kbd_Data ( UV1, "End of Report")
    Append_UV_Kbd_Data ( UV1, CRLF )
    Append_UV_Kbd_Data ( UV1, FF )
   
    // Append to a TC user variable, the directory in which TC is installed
    Append_UV_Kbd_Data ( UV1, %TC2% )
   
    // Append the floating point number 1.5 to UV1 (and use the short version of the command: Append)
    Append ( UV1, 1.5 )
   
  

  Append_UV_Select_Data / Append_UV_Select_Data2

    Append_UV_Select_Data( UV, SELECT_ITEM )
    Append_UV_Select_Data( UV, SELECT_ITEM, ERR_LABEL )
    Append_UV_Select_Data( UV, SELECT_ITEM, ERR_LABEL, FORMAT)
    
  Starting in version 3.1.0, the suffix-2 commands were added, and they have added a new first parameter, the ODBC data source alias:
  
    Append_UV_Select_Data2( DataSourceAlias*, UV, SELECT_ITEM ... )
    
  

  Append to a TC user variable from a column of a report. The report is the result of an SQL SELECT statement or command, followed by a Perform_Fetch command.

  DataSourceAlias*	For the suffix-2 version of the command, a ODBC data source alias defined in a Database / DB command.
  UV*	Target TC user variable; not to be confused with the user variables resident in the data collection terminals.
  SELECT_ITEM	A number indicating the column position in the report from which the data is copied. The range is from 1 to the number of columns the SELECT should retrieve. Columns, or column functions (for example, MAX(SER_NUM)), are numbered in the order they occur in the SELECT statement. Append_UV_Select_Item will accept a user variable for the select item number.
  ERR_LABEL	Branch to this label if no data row was retrieved by the Perform_Fetch or no Perform_Fetch has been attempted. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends. The label is optional; if not specified, the script will always execute the next command step.
  FORMAT	Optional format string, specifying the width and precision of the output for the column. The format string has 3 optional subsections: [flags][width][.precision] where: flags Can be one or more of the following. - Left-justify the result within the field width (default is right-justify). + Prefix the output value with a sign (+ or -) if the output value is of a signed type. ' ' (blank) Prefix the output values with a blank if the output value is signed and positive. The "+" flag overrides the blank flag if both appear, and a positive signed value will be output with a sign. width Is a non-negative decimal integer controlling the minimum number of characters in the output. If the number of characters in the output is less than the specified width, blanks are added on the left or right (depending on whether the "-" flag is specified) until the minimum width is reached (not useful for left-justified numbers). The width never causes a value to be truncated; if the number of characters in the output value is greater than the specified width, or width is not given, all characters of the value are in the output (subject to the precision specification). .precision Is a non-negative decimal integer, preceded by a period, that specifies the number of characters to be in the output or the number of decimal places. Unlike the width specification, the precision can cause truncation of the output value or rounding of a floating-point value. The effect of the precision and the default when no precision is specified depends on the type of data being formatted: Integers Precision specifies the minimum number of digits in the output. If the number of digits in the value is less than the precision, the output value is padded on the left with zeros. The value is not truncated if the number of digits exceeds the precision. If the precision is set to 0, or omitted, the precision is set to 1. Floating-Point (Real) Precision specifies the number of digits after the decimal point. If a decimal point appears, at least one digit appears before it. The value is rounded to the appropriate number of digits. The default precision is zero. Character Strings Precision specifies the maximum number of characters in the output. Characters in excess of the precision are not in the output. The default is that all characters are used.

  Example:
   
    // Append 2nd column of results to user variable vXX
    Append_UV_Select_Data ( vXX, 2, No_data )
   
    // Append 3rd column of results to UV1, formatted
    // 12 wide with 3 places to right of decimal
    UV_Math( ColNum, =, 3, 0.0 )
    Append_UV_Select_Data ( UV1, ColNum, No_data, 12.3 )
    
     // Append 2nd column of results from data source Inventory to user variable vXX
    DB( oERPDATA, INVENTORY ) 
    Set_UV_Kbd_Data( gInvDS, "INVENTORY" )
    
    Append_UV_Select_Data2 ( gInvDS, vXX, 2, No_data )
  

  Append_UV_Seq_Num

    Append_UV_Seq_Num( UV )
  

  Append to the end of a TC user variable from the sequence number maintained by TC for each session. When TC starts, the sequence number is reset to start at '0000'. Each time this command is used, the sequence number will be incremented by 1. When '9999' is reached, the number is set back to '0000'.

  UV	Target TC user variable; not to be confused with the user variables resident in the data collection terminals.

  Example:
   
    // Append sequence number to UV 1
    Append_UV_Seq_Num ( UV1 )
  

  Append_UV_UV

    Append_UV_UV ( TARGET_UV, SOURCE_UV, START*, LENGTH* )
  

  Append the entire contents of one TC user variable to the end of another TC user variable.

  Note: This is a more concise form for one case of the Append_UV_Data_Part command which also can be used to append one TC user variable to another.

  Note: Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a TC user variable by using the user variable's name or the notation UVn, where n ranges from one to 250 or the maximum defined by Define_UVs.

  TARGET_UV	The TC user variable to which the source variable is appended; not to be confused with the user variables resident in the data collection terminals.
  SOURCE_UV	The TC user variable that is appended to the target user variable; not to be confused with the user variables resident in the data collection terminals.
  START*	The starting position within the specified user variable. 0 is the beginning of the data. This parameter and the following parameter are optional. If only one of these two optional parameters is give, it is assumed to be the START position.
  LENGTH*	The length of data to append from the user variable, starting at the START position. A length of 0 means to take all data from the specified starting point to the end of the user variable.

  Examples:
   
    // Append all of UV2 to the end of UV5
    Append_UV_UV ( UV5, UV2 )
   
    // Append to UV5 from UV2 at position 2 for a length of 3
    Append_UV_UV ( UV5, UV2, 2, 3 )
  

  Append_UV_Xact_Data

    Append_UV_Xact_Data( UV, DATA_PART, START*, LENGTH* )
  

  This function is an alias for Append_UV_Data_Part. Refer to Append_UV_Data_Part for a full description of this function.

  Application

    Application ( NAME )
  

  Specify the application name to use when in REMOTE_VALIDATION mode or in DATA_REQUEST mode. This command has no effect in transaction mode.

  In REMOTE_VALIDATION mode, the application name does not have to be provided specifically. If not provided, a default application name, based on the controller ID, is generated.

  In DATA_REQUEST mode, the application name must be provided. This name is part of every data request and is used by DCConnect to route the requests to the proper application. This name is used by the TC session when it registers with DCConnect to receive data requests. A default name is never appropriate.

  In both REMOTE_VALIDATION and DATA_REQUEST mode, the application name can be specified on the command line instead of the script. If the application name is provided on the command line, it is an error to also provide it in the script using this command. See Starting TC from a Command Line for more details.

  NAME

  An up-to-32 character name to use. The name must match the application name that is put into all data requests that are going to be processed by the TC session making this call. The name may be enclosed in double quotes. If it is, the double quotes are removed before the name is stored. The case of the name is important.

  Example:
   
    // Define the application name to be TIME_AND_ATTENDANCE
    Application ( TIME_AND_ATTENDANCE )
  

  Begin_SQL / Begin_SQL2 / Begin_Select / Begin_Select2

    Begin_SQL ()
    Begin_SQL2 ()
    Begin_Select ()
    Begin_Select2 ()
  

  Begin_SQL2 was added as an interchangeable synonym for Begin_SQL in version 3.1.0e, intended to be paired with End_SQL2. Begin_Select / Begin_Select2 were also added in version 3.1.0e.

  Start a free-form SQL statement area. All data in the command file up to the ending End_SQL / End_SQL2 / End_Select / End_Select2 command is appended into the SQL statement.

  See End_SQL / End_SQL2 / End_Select / End_Select2 for more details about these Begin* / End* commands and a more complete example. Also see Free-Form SQL Statements for a complete explanation of using the free-form SQL functions.

  Example:
   
    Begin_SQL()
  

  Begin_UV

    Begin_UV()
  

  Start a formatted user variable text area. All data in the command file up to the ending End_UV command is appended into the user variable string.

  See End_UV for a complete description and more complete example of how to use a formatted user variable text area.

  Example:
   
    Begin_UV()
  

  Call

    Call SUB_NAME ( parm1, parm2, ..., parmN  )
  

  This command calls a defined subroutine script. As of 3/23/2005 you can have over 6000 subroutines and StartMatch scripts combined. (Earlier limits were 250 (fix packs D-F for version 1.40) and 125 (prior to fix pack D for version 1.40)).

  The subroutine script is defined with a Sub or a StartSubroutine command and EndSub / EndSubroutine command.

  SUB_NAME

  The name of the subroutine you want to call.

  parm1, ..., parmN

  The set of parameters to pass to the subroutine. The parameters may be any combination of global user variables, local user variables, string constants or numeric constants. String constants are enclosed in double quotes and can be no longer than 255 characters (Prior to TC 3.1.0b, the max length was 127 characters). Numeric constants do not have to be enclosed in double quotes and can be any base 10 number, optionally having a leading negative sign and optionally having a decimal point. Both Declared local user variables and parameters passed to subroutines are stored in Transaction Connection's local user variable stack array. This array has a capacity of 1024 items; your script must have no path through the code which can cause more than 1024 local user variables (Declare statements) and/or parameters in a subroutine calling stack to be encountered. For example, you can have a main StartMatch / EndMatch block which declares 50 local user variables and passes 14 of them to a subroutine, which in turn declares 50 local user variables and passes 14 to a lower level, and so on for 14 more layers deep before you run out of stack space. User variables are passed by address (reference) so the called routine may change them before returning. Temporary storage is created for string and numeric constants and the address of this storage is passed to the routine (which may then change what is in the storage, but the calling script will never be able to see what the new value was). The number of parameters passed must match the number defined in the Sub command.

  Note that you can use the Call command to call a subroutine which was defined with the StartSubroutine / EndSubroutine commands, but you cannot pass any parameters to that style of subroutine. Define the subroutine using the Sub command if you want to be able to pass parameters.

  Example:
   
    Name_UV( UV1, gUserID )
    StartMatch( "MOVE", TXNFIELD1, 0, 4 )
   
      Declare( ItemNumber )
      Declare( Short_Item )
   
      Set_UV_Data_Part( gUserID,    TXNFIELD2, 0, 0 ) // User from txn
      Set_UV_Data_Part( ItemNumber, TXNFIELD3, 0, 0 ) // Item fromtxn
   
      // Ask my utility routine to convert input item to
      // the ERP system's short_item number and return it
      // in Short_Item
      Call ConvertItem( gUserID, ItemNumber, "CNV_SHORT", Short_Item  )
   
      ...
    EndMatch()
   
   
    Sub ConvertItem( InUserID, InItem, InMode, OutItem )
   
      Declare( TempItem )
   
      ... logic to check conversion mode desired (InMode) and
          do conversion....
   
      Set_UV_UV( OutItem,  TempItem )
   
      // Note that a TC trace log will show that changing the value
      // of OutItem affected the named user variable Short_Item at the
      // higher level:
      // " Short_Item<-OutItem (4): 7589 "
   
    EndSub()
  

  Call_Subroutine

    Call_Subroutine( SUB_NAME )
    CallSubroutine( SUB_NAME )
  

  Note: The Call command provides enhanced function and should be used instead of Call_Subroutine for all new scripts.

  This command calls a defined subroutine script. As of 3/23/2005 you can have over 6000 subroutines and StartMatch scripts combined. (Earlier limits were 250 (fix packs D-F for version 1.40) and 125 (prior to fix pack D for version 1.40)).

  The subroutine script is defined with a StartSubroutine command and EndSub / EndSubroutine command.

  SUB_NAME

  The name of the subroutine you want to call.

  Example:
   
    Call_Subroutine( Set_Update_On_Error_Group )
  

  Capture_Screen

    Capture_Screen (TARGET_UV )
  

  Use this command to capture the entire host screeen and write it to a TC user variable. The target user variable must be one of the large global user variables since the size of other variables is only 235 bytes - which cannot accommodate the typical screen size of 24 rows x 80 columns.

  This command clears the target UV before writing the screen to it.

  TC will add a carriage return and linefeed to the end of every screen row, as it is copied to the UV.

  TARGET_UV

  This must be one of the large global user variables (default UV241 - UV250)

  Example:
   
    // Capture the screen to a large user variable.
    Name_UV(UV250, uvScreen)
   
    ...
   
    Capture_Screen(uvScreen)
   
  

  Change_Term_State / Change_Terminal_State

    Change_Term_State ( TERMINAL_NAME*, SERVICE_STATE_UV, POLLING_STATE_UV)
    Change_Term_State ( TERMINAL_NAME*, SERVICE_STATE_UV, POLLING_STATE_UV, OPT_ERR_LABEL)
  

  Send a change terminal state request to the DCConnect Server to change the desired service and/or desired polling state of a specific terminal. When a terminal is out of service, it is not allowed to run transaction programs. When a terminal has polling disabled the DCConnect Server does not attempt to communicate with it. The 'desired' state is what the DCConnect Server tries to set the terminal to. But if the terminal is currently not responding, for example, the server will not be able to change its service state until it does begin responding.

  • The Service State can be set to any of the following:

    0 =	Do not change the service state.
    1 =	Put the terminal into service.
    2 =	Put the terminal out of service.

  • The Polling State can be set to any of the following:

    0 =	Do not change the Polling state.
    1 =	Disable polling of the terminal.
    2 =	Enable polling of the terminal.

  Note: Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "15", "ShippingMailbox", and so forth) or as the current value of a TC user variable by using the user variable's name or the notation UVn, where n ranges from one to 250 or the maximum defined by Define_UVs.

  that can be returned.

  TERMINAL_NAME*	Literal terminal name or the User variable containing the name of the terminal to change.
  SERVICE_STATE_UV	User variable containing a value from 0 - 2 indicating what should be done with the service state (see above for the meaning of these values).
  POLLING_STATE_UV	User variable containing a value from 0 - 2 indicating what should be done with the polling state (see above for the meaning of these values).
  OPT_ERR_LABEL	If an error label is provided, control will branch to this label if an error occurs when trying to change the terminal state (e.g. the DCConnect Server is not running). The data part LAST_ERROR will contain the error code. If the label name is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends. The label is optional; if not specified, the script will always execute the next command step - unless the error causes TC to terminate.

  Examples:
   
    ...
    Declare ( uvNewService )
    Declare ( uvNewPolling )
    ...
   
    // Don't let DCConnect unavailability end the TC session
    No_Terminate_From_DCConnect
  
    // Disable polling but don't change the service state
    Set_UV_Kbd_Data ( uvNewPolling, "1" ) 
    Set_UV_Kbd_Data ( uvNewService, "0" ) 
  
    // Set the state for the terminal named "Dock_Door_1"
    Change_Term_State( "Dock_Door_1", uvNewService, uvNewPolling, ChangeError )
  
  
    ...
  ChangeError:
    
    // Handle error trying to change state
   
   

  Check_Color

    Check_Color ( COLOR, AREA, ROW*, COL*, TIME_LIMIT*, LABEL, CONDITION)
    If Check_Color ( COLOR, AREA, ROW*, COL*, TIME_LIMIT*, CONDITION)
  

  This function checks a screen location for presence of the specified screen foreground (character) or background color. It re-checks the location four times per second up to the time limit you specify. This feature is used to check the screen for error conditions or to determine if the correct screen is displayed.

  The first form shown branches to a LABEL or call a subroutine of that name based on the color either being found or not found on the screen, as specified by the CONDITION.

  The second form lets you use inline conditionally executed steps rather than a goto or subroutine call, basically using Check_Color as a special type of If...Else logic.

  Note: The original form of the Check_Color command did not specify the CONDITION, and would always branch to the label if the highlight was not found. This syntax is still supported, but discouraged. The CONDITION is required for the If Check... form.

  See Screen_Width if your host session runs in other than 80-column mode.

  Note:

  1. Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a user variable by using the user variable's name or the notation UVn, where n ranges from 1 to 250 or the maximum defined by Define_UVs.

  2. When running in Trace mode, the trace file data includes information on what foreground and background color was detected during a Check_Color command. This can be very helpful in developing your application in an iterative manner.

  COLOR	One of the following color names to check for at the row and column position. Note: The attribute below is the color you actually see on your PCOMM 3270 or 5250 emulation screen. This may not be the color specified by the host application if you have changed the color/highlighting mappings for your emulator session. Be sure to note for future reference the session color settings so the script works properly on other emulator sessions. Use the Check_Highlight command to check the attribute as sent by the host data stream. BLACK GRAY BLUE LIGHT BLUE GREEN LIGHT GREEN CYAN LIGHT CYAN RED LIGHT RED MAGENTA LIGHT MAGENTA BROWN YELLOW WHITE WHITE HIGH INTENSITY
  AREA	Specify FOREGROUND for the character color, or BACKGROUND for the color of the screen fill.
  ROW*	An integer indicating the row on the screen where to look for the highlight. Row 1 is the top row.
  COL*	An integer indicating the column on the screen where to look for the highlight. Column 1 is the left-hand column. No range checking is done for the row and column parameters. You must use valid values based on the size of the emulation session set up in Communications Manager.
  TIME_LIMIT*	How many seconds to wait for a match before taking the not-found branch. The range is 0 to 65,535. A limit of 0 means to look once and then proceed.
  LABEL	A label to branch to if the color is either found or not found, as specified in the CONDITION. The maximum label length is 31 characters. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends. Note: If a LABEL is not provided, the command is treated as having an If...Else type of form, and you should use the If Check... format. See the Example that follows.
  CONDITION	This parameter determines if the command should test for the characteristic to be either FOUND, NOT_FOUND, or NOT_FOUND_IMMED. Refer to Check... Check_XXX Command Logic Modes for a discussion of how the various Check... commands behave for each condition value.

  Examples:
   
    // First Form: See if host app turns input field at row
    // 10 red to indicate error.
    // Goto the label OK_Input_Row_10 if color is NOT red.
    Check_Color ( Red, BACKGROUND, 10, 1, 0, Label_OK_Input_Row_10, NOT_FOUND)
   
    // Handle the error....
   
    // Same application, but reverse the test condition
    // Call the subroutine Error_Input_Row_10 if color IS red.
    Check_Color ( Red, BACKGROUND, 10, 1, 0, Error_Input_Row_10, FOUND )
   
    // Continue processing next field....
   
    // Second Form: Same application again, but handle good
    // or bad conditions inline.
    If Check_Color ( Red, BACKGROUND, 10, 1, 0, FOUND )
     {
      // Color was red
      // Handle error....
     }
    Else
     {
      // Color was not red
      // Handle good data
     }
  

  Check_Cursor

    Check_Cursor ( ROW*, COL*, TIME_LIMIT*, LABEL, CONDITION)
    If Check_Cursor ( ROW*, COL*, TIME_LIMIT*, CONDITION)
  

  This function checks a screen location for presence of the cursor. It will re-check the location 4 times per second up to the time limit you specify. This feature is used to check the screen for error conditions or to determine if the correct screen is displayed.

  The first form shown will branch to a LABEL (or call a subroutine of that name) based on the cursor either being found or not found on the screen, as specified by the CONDITION.

  The second form lets you use inline conditionally executed steps rather than a goto or subroutine call, basically using Check_Cursor as a special type of If...Else logic.

  Note:

  The original form of the Check_Cursor command did not specify the CONDITION, and would always branch to the label if the highlight was not found. This syntax is still supported, but discouraged. The CONDITION is required for the If Check... form.

  See Screen_Width if your host session runs in other than 80-column mode.

  Note:

  Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a user variable by using the user variable's name or the notation UVn, where n ranges from 1 to 250 or the maximum defined by Define_UVs.

  ROW*	An integer indicating the row on the screen where to look for the cursor. Row 1 is the top row.
  COL*	An integer indicating the column on the screen where to look for the cursor. Column 1 is the left-hand column. No range checking is done for the row and column parameters. You must use valid values based on the size of the emulation session set up in Communications Manager.
  TIME_LIMIT*	How many seconds to wait for a match before taking the not-found branch. The range is 0 to 65,535. A limit of 0 means to look once and then proceed.
  LABEL	A label to branch to if the cursor is either found or not found, as specified in the CONDITION. The maximum label length is 31 characters. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends. Note: If a LABEL is not provided, the command is treated as having an If...Else type of form, and you should use the If Check...format. See the Example that follows.
  CONDITION	This parameter determines if the command should test for the characteristic to be either FOUND, NOT_FOUND, or NOT_FOUND_IMMED. Refer to Check_XXX Command Logic Modes for a discussion of how the various Check... commands behave for each condition value.

  Examples:
   
    // First Form: If host app has not placed the cursor back
    // in row 1, column 1, go handle a 'not running' condition.
    Check_Cursor ( 1, 1, 5, LABEL_NOT_RUNNING, NOT_FOUND)
   
    // Same application, but reverse the test condition
    Check_Cursor ( 1, 1, 5, LABEL_RUNNING, FOUND )
   
    // Second Form: Same application again, but handle good
    // or bad conditions inline.
    If Check_Cursor ( 1, 1, 5, FOUND )
     {
      // Cursor was found at 1,1 within 5 seconds...
     }
    Else
     {
      // Cursor was NOT found at 1,1 within 5 seconds...
     }
  

  Check_Highlight

    Check_Highlight  ( HIGHLIGHT, ROW*, COL*, TIME_LIMIT*, LABEL, CONDITION)
    If Check_Highlight  ( HIGHLIGHT, ROW*, COL*, TIME_LIMIT*, CONDITION)
  

  This function checks a screen location for presence of the specified screen highlighting. It will re-check the location 4 times per second up to the time limit you specify. This feature is used to check the screen for error conditions or to determine if the correct screen is displayed.

  The first form shown will branch to a LABEL (or call a subroutine of that name) based on the highlight either being found or not found on the screen, as specified by the CONDITION.

  The second form lets you use inline conditionally executed steps rather than a goto or subroutine call, basically using Check_Highlight as a special type of If...Else logic.

  Note:

  The original form of the Check_Highlight command did not specify the CONDITION, and would always branch to the label if the highlight was not found. This syntax is still supported, but discouraged. The CONDITION is required for the If Check... form.

  See Screen_Width if your host session runs in other than 80-column mode.

  Note:

  Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a user variable by using the user variable's name or the notation UVn, where n ranges from 1 to 250 or the maximum defined by Define_UVs.

  HIGHLIGHT	One of the following highlight names to check for at the row and column position. Note: The following attributes are specified by the host application in the 3270/5250 data stream. You may not actually see the attribute on your PCOMM emulator screen due to constraints of the GUI window (for example, lack of blinking text) or color remapping done by your configuration file. Use the Check_Color command to check the color of foreground and background as shown on your PC emulator session window. NORMAL // No special highlights BLINK // Blinking text REVERSE // Reverse video UNDERLINE // Underscoring type input fields COLUMN SEPARATORS // 5250 character position markers // Color is not supported on the 5250; // Use Check_Color DEFAULT COLOR // 3270 No specified color BLUE // 3270 Character color (foreground) RED // 3270 Character color (foreground) PINK // 3270 Character color (foreground) GREEN // 3270 Character color (foreground) TURQUOISE // 3270 Character color (foreground) YELLOW // 3270 Character color (foreground) WHITE // 3270 Character color (foreground)
  ROW*	An integer indicating the row on the screen where to look for the highlight. Row 1 is the top row.
  COL*	An integer indicating the column on the screen where to look for the highlight. Column 1 is the left-hand column. No range checking is done for the row and column parameters. You must use valid values based on the size of the emulation session set up in Communications Manager.
  TIME_LIMIT*	How many seconds to wait for a match before taking the not-found branch. The range is 0 to 65,535. A limit of 0 mean to look once and then proceed.
  LABEL	A label to branch to if the highlight is either found or not found, as specified in the CONDITION. The maximum label length is 31 characters. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends. Note: If a LABEL is not provided, the command is treated as having an If...Else type of form, and you should use the If Check... format. See the examples.
  CONDITION	This parameter determines if the command should test for the characteristic to be either FOUND, NOT_FOUND, or NOT_FOUND_IMMED. Refer to Check_XXX Command Logic Modes for a discussion of how the various Check... commands behave for each condition value.

  Example:
   
    // First Form:
    // See if host app has NOT put up an underscored input field
    Check_Highlight ( UNDERLINE, 10, 1, 0, No_Input_Field, NOT_FOUND )
   
    // Same application, but reverse the test condition
    // See if host app has put up an underscored input field
    Check_Highlight ( UNDERLINE, 10, 1, 0, Yes_Input_Field, FOUND )
   
    // Second Form: Same application again, but handle good
    // or bad conditions inline.
    // See if host app has put up an underscored input field
    If Check_Highlight ( UNDERLINE, 10, 1, 0, FOUND )
     {
      // Copy input to field...
     }
    Else
     {
      // Handle error -- no input field...
     }
  

  Check_Busy

    Check_Busy ( TIME_LIMIT*, LABEL, CONDITION )
    If Check_Busy ( TIME_LIMIT*, CONDITION )
  

  This function checks the current setting of the host's Busy indicator. It re-checks four times per second up to the time limit you specify. This command is valid only for 5250 emulation.

  The first form shown branches to a LABEL or calls a subroutine of that name based on the Busy indicator being set, as specified by the CONDITION.

  The second form lets you use inline conditionally-executed steps rather than a goto or subroutine call, basically using Check_Busy as a special type of If...Else logic.

  Note: Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a user variable by using the user variable's name or the notation UVn, where n ranges from 1 to 250 or the maximum defined by Define_UVs.

  TIME_LIMIT*	How many seconds to wait for the indicator to be turned on before taking the not-found branch. The range is 0 to 65,535. A limit of zero means to check once and then proceed.
  LABEL	A label to branch to if the indicator is found to be on or off, as specified in the CONDITION. The maximum label length is 32 characters. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control returns to the next command when the subroutine ends. Note: If a LABEL is not provided, the command is treated as having an If...Else type of form, and you should use the If Check... format. See the Example that follows.
  CONDITION	This parameter determines if the command should test for the characteristic to be either FOUND, NOT_FOUND, or NOT_FOUND_IMMED. Refer to Check_XXX Command Logic Modes for a discussion of how the various Check... commands behave for each condition value.

  Examples:
   
    // First Form:
    // See if the  indicator is currently on
    Check_Busy ( 0, HANDLE_BUSY_ON, FOUND )
   
    // Same application, but reverse the test condition
    // See if the indicator is currently off
    Check_Busy ( 0, HANDLE_BUSY_OFF, NOT_FOUND )
   
   
    // Second Form: Same application again, but handle good or
    // bad conditions inline:
   
    // Wait for system to go non-busy for up to 5 seconds after
    // pressing Enter key, then check if there was an application
    // error which set the input inhibited indicator
   
    Send_To_Host( ENTER )
   
    If Check_Busy (5, NOT_FOUND_IMMED )
     {
      // AS/400 finished thinking within 5 seconds.
      // Now see if the application left the screen
      // 'input-inhibited', indicating it did not like
      // our last input data.
      If Check_II( 0, FOUND )
       {
        // Handle rejected data error
       }
     }
    else
     {
      // Screen did not unlock due to busy condition
      // in a reasonalble length of time.
      // Handle this error...
     }
   
    // Otherwise AS/400 responded and data was accepted...
  

  Check_II

    Check_II ( TIME_LIMIT*, LABEL, CONDITION )
    If Check_II ( TIME_LIMIT*, CONDITION )
  

  This function checks the current setting of the host's Input Inhibited indicator. It re-checks four times per second up to the time limit you specify. This command is valid only for 5250 emulation.

  The first form shown branches to a LABEL or calls a subroutine of that name based on the Input Inhibited indicator being set, as specified by the CONDITION.

  The second form lets you use inline conditionally-executed steps rather than a goto or subroutine call, basically using Check_MW as a special type of If...Else logic.

  Note: Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a user variable by using the user variable's name or the notation UVn, where n ranges from 1 to 250 or the maximum defined by Define_UVs.

  TIME_LIMIT*	How many seconds to wait for the indicator to be turned on before taking the not-found branch. The range is 0 to 65,535. A limit of zero means to check once and then proceed.
  LABEL	A label to branch to if the Message Waiting indicator is found to be on or off, as specified in the CONDITION. The maximum label length is 32 characters. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control returns to the next command when the subroutine ends. Note: If a LABEL is not provided, the command is treated as having an If...Else type of form, and you should use the If Check... format. See the Example that follows.
  CONDITION	This parameter determines if the command should test for the characteristic to be either FOUND, NOT_FOUND, or NOT_FOUND_IMMED. Refer to Check_XXX Command Logic Modes for a discussion of how the various Check... commands behave for each condition value.

  Examples:
   
    // First Form:
    // See if the Busy indicator is currently on
    Check_II ( 0, HANDLE_II_ON, FOUND )
   
    // Same application, but reverse the test condition
    // See if the indicator is currently off
    Check_II ( 0, HANDLE_II_OFF, NOT_FOUND )
   
   
    // Second Form: Same application again, but handle good or
    // bad conditions inline:
   
    // Wait for system to go non-busy for up to 5 seconds after
    // pressing Enter key.
   
    Send_To_Host( ENTER )
   
    If Check_Busy (5, NOT_FOUND_IMMED )
     {
      // AS/400 finished thinking within 5 seconds.
      // Now see if the application left the screen
      // 'input-inhibited', indicating it did not like
      // our last input data.
      If Check_II( 0, FOUND )
       {
        // Handle rejected data error
       }
     }
    else
     {
      // Screen did not unlock due to busy condition
      // in a reasonalble length of time.
      // Handle this error...
     }
   
   // Otherwise AS/400 responded and data was accepted...
  

  Check_MW

    Check_MW ( TIME_LIMIT*, LABEL, CONDITION )
    If Check_MW ( TIME_LIMIT*, CONDITION )
  

  This function checks the current setting of the host's Message Waiting indicator. It re-checks four times per second up to the time limit you specify. This command is valid only for 5250 emulation.

  The first form shown branches to a LABEL or calls a subroutine of that name based on the Message Waiting indicator being set, as specified by the CONDITION.

  The second form lets you use inline conditionally executed steps rather than a goto or subroutine call, basically using Check_MW as a special type of If...Else logic.

  Note: Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a user variable by using the user variable's name or the notation UVn, where n ranges from 1 to 250 or the maximum defined by Define_UVs.

  TIME_LIMIT*	How many seconds to wait for the Message Waiting indicator to be turned on before taking the not-found branch. The range is 0 to 65,535. A limit of zero means to check once and then proceed.
  LABEL	A label to branch to if the Message Waiting indicator is found to be on or off, as specified in the CONDITION. The maximum label length is 32 characters. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control returns to the next command when the subroutine ends. Note: If a LABEL is not provided, the command is treated as having an If...Else type of form, and you should use the If Check... format. See the Example that follows.
  CONDITION	This parameter determines if the command should test for the characteristic to be either FOUND, NOT_FOUND, or NOT_FOUND_IMMED. Refer to Check_XXX Command Logic Modes for a discussion of how the various Check... commands behave for each condition value.

  Example:
   
    // First Form:
    // See if the Message Waiting indicator is currently on
    Check_MW ( 0, HANDLE_MW_ON, FOUND )
   
    // Same application, but reverse the test condition
    // See if the Message Waiting indicator is currently off
    Check_MW ( 0, HANDLE_MW_OFF, NOT_FOUND )
   
    // Second Form: Same application again, but handle good or
    // bad conditions inline.
    // See if the Message Waiting indicator is currently on
    If Check_MW (0, FOUND)
     {
      // Try to display messages
     }
    else
     {
      // Set flag saying there are no messages waiting
     }
  

  Check_Screen

    Check_Screen  (STRING, ROW*, COL*, TIME_LIMIT*, LABEL, CONDITION)
    Check_Screen  (DATA_PART, START*, LEN*, ROW*, COL*, TIME_LIMIT*, LABEL, CONDITION)
    If Check_Screen  (STRING, ROW*, COL*, TIME_LIMIT*, CONDITION)
    If Check_Screen  (DATA_PART, START*, LEN*, ROW*, COL*,TIME_LIMIT*, CONDITION)
  

  This function searches the screen or portion of the screen for a particular string. This feature is used to check the screen for error conditions or to determine if the correct screen is displayed. It also can be used to check data that previously was written to the screen.

  The first two forms shown will branch to a LABEL (or call a subroutine of that name) based on the search characters either being found or not found on the screen, as specified by the CONDITION. The search string comes from either a constant value in the script, or from one of the various data parts available for use.

  The third and fourth forms let you use inline conditionally executed steps rather than a goto or subroutine call, basically using Check_Screen as a special type of If...Else logic. Alternatives for specifying the search string are the same as for the other forms of the command.

  Note:

  1. The original form of the Check_Screen command did not specify the CONDITION, and would always branch to the label if the string was not found. This syntax is still supported, but discouraged. The CONDITION is required for the If Check... form.

  2. Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a TC user variable by using the user variable's name or the notation UVn, where n ranges from 1 to 250 or the maximum defined by Define_UVs.

  See Screen_Width if your host session runs in other than 80-column mode.

  STRING	The string to look for on the screen. The maximum length is 255 characters. The string is case sensitive.
  DATA_PART	This specifies one of various predefined parts of the terminal transaction or other information that becomes part of the data appended to the target user variable. The predefined parts are listed in Data Parts. The data parts that are valid will vary depending on whether the TC session is currently running in transaction, validation or data request mode.
  START*	The starting position within the selected data part. Zero is the beginning of the data.
  LENGTH*	The length of data to use from the data part, starting at the START position. Refer to Data Parts for the meaning of a 0 length for a given data part. It may be ignored, it may mean return no data or it may mean take all data from the START position.
  ROW*	An integer indicating the row on the screen where to look for the string. Row 1 is the top row. Set this and COL to 0 to look everywhere.
  COL*	An integer indicating the column on the screen where to look for the string. Column 1 is the left-hand column. Set this and ROW to 0 to look everywhere. No range checking is done for the row and column parameters. You must use valid values based on the size of the emulation session set up in Communications Manager.
  TIME_LIMIT*	How many seconds to wait for a match before taking the not-found branch. The range is 0 to 65,535. A limit of 0 means to look once and then proceed.
  LABEL	A label to branch to if the text is either found or not found, as specified in the CONDITION. The maximum label length is 31 characters. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends. Note: If a LABEL is not provided, the command is treated as having an If...Else type of form and you should use the If Check... format. See the Example that follows.
  CONDITION	This parameter determines if the command should test for the characteristic to be either FOUND, NOT_FOUND, or NOT_FOUND_IMMED. Refer to Check... Check_XXX Command Logic Modes for a discussion of how the various Check... commands behave for each condition value.

  Examples:
   
    // First Form:
    //  Look for the string "RUNNING" starting on line 24, column 61
    //   of the host screen.  Keep trying for 5 seconds.  If the string
    //   is NOT found, branch to the label "lbl_Not_Running".
    Check_Screen ("RUNNING", 24, 61, 5, lbl_Not_Running, NOT_FOUND)
   
   
    // Second Form:  Same as first, but you could use some variable
    // data from the incoming transaction rather than a constant, and
    // call a subroutine if the data is found on the screen.
    ...
    Clear_UV( UV1 )
    Append_UV_Xact_Data( UV1, TXNFIELD1, 0, 0 )
    Check_Screen (UV1, 0, 0, 24, 61, 5, sub_Found_Data, FOUND)
    ...
   
    // Subroutine called when data if found on host screen
    StartSubroutine( sub_Found_Data )
    ...
   
   
    // Third Form:  Handle good or bad conditions inline.
    //  Look for the string "RUNNING" starting on line 24, column 61
    //   of the host screen.  Keep trying for 5 seconds.  If the string
    //   is found, continue processing; otherwise, handle it as an error.
    If Check_Screen ("RUNNING", 24, 61, 5, FOUND)
     {
      // Continue processing...
     }
    Else
     {
      // Handle error...
     }
  

  Clear_Mailbox

    Clear_Mailbox ( MAILBOXNAME* )
    Clear_Mailbox ( MAILBOXNAME*, OPT_ERR_LABEL )
  

  Clear all transactions from a DCConnect mailbox.

  Note: Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a TC user variable by using the user variable's name or the notation UVn, where n ranges from one to 250 or the maximum defined by Define_UVs.

  MAILBOXNAME*

  The name of a mailbox to be cleared. This must be defined in the DCConnect configuration. This name is case-sensitive. If not using a user variable for the mailbox name, it must be enclosed in double quotes.

  OPT_ERR_LABEL

  If an error label is provided, control will branch to this label if an error occurs when trying to clear the mailbox (e.g. the DCConnect Server is not running). The data part LAST_ERROR will contain the error code. If the label name is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends. The label is optional; if not specified, the script will always execute the next command step - unless the error causes TC to terminate.

  Examples:
   
    ...
    Name_UV(NEXT_UV, uvMailboxName)
    ...
   
    // Clear the mailbox with the name Sample_DCC.
    Clear_Mailbox( "Sample_DCC" )
  
    // Clear the same mailbox but get the name from a user variable and branch to an error label if the operation fails
    Set_UV_Kbd_Data(uvMailboxName, "Sample_DCC")
    Clear_Mailbox( uvMailboxName, ClearFailed)
  
    Goto ( ClearSucceeded )
  
  ClearFailed:
    // Handle failure
  
  ClearSucceeded:
    // Handle success
   
  

  Clear_UV

    Clear_UV ( UV )
  

  Clear a TC user variable.

  UV	The TC user variable. (This is NOT a terminal user variable.)

  Example:
   
    Clear_UV ( UV1 )
  

  Close_Cursor / Close_Cursor2

    Close_Cursor()
    
  Starting in version 3.1.0, the suffix-2 commands were added, and they have added a new first parameter, the ODBC data source alias:
  
    Close_Cursor2( DataSourceAlias* )
  

  The database will attach a LOCK to the data row where your SELECT cursor is currently located. The cursor is moved down the rows of your query report using the Perform_Fetch command. As long as the LOCK exists, no other process will be able to update the locked row. You must move the cursor (Perform_Fetch) or close the cursor with this command to remove the LOCK.

  It is good practice to close the cursor as soon as possible during the script. Close it as soon as you have done all the Perform_Fetch and Append_UV_Select_Data calls in the script. This will minimize the amount of time other sessions of TC are required to wait due to row locks.

  The cursor is automatically closed by the EndKey, EndVal, EndMatch, and End / End_TC commands (all cursors if multiple data sources are used).

  DataSourceAlias*

  For the suffix-2 version, the required first parameter is an ODBC database alias as a literal or contents of a user variable. (as defined in a Database / DB command). The SQL will be executed against that data source.

  Example:
   
    Close_Cursor()
    
    Close_Cursor2(myDSAlias)
  

  Close_File_Data

    Close_File_Data( )
  

  This command closes a flat file that was previous opened for reading data into a user variable by calling Open_File_Data.

  Example:
   
    // Close the file opened with Open_File_Data
    Close_File_Data( )
  

  Close_When_Complete

    Close_When_Complete
  

  This command tells TC to close its display window when TC completes (due to an error or because an End Command was encountered). By default, TC will leave its window open with the Completed status shown so you can inspect the execution and error windows. Close_When_Complete is particularly useful when you are using a command file to start TC and have a loop which is to restart TC automatically.

  This command may be placed anywhere in the script file to override the default operation of TC.

  Example:
   
    // Close the window when completed
    Close_When_Complete
  

  Cntlr

    Cntlr ( ID )
  

  This function is used to specify the single character to use as an arbitrary controller identification. The specified character is used in the name of the error log file, transaction log file, and trace log file that can be generated by each TC session that is running. If the TC session will be processing remote validation requests then the controller ID is part of the default application name used when the TC session registers with DCConnect to receive validation requests.

  If more than one TC session will be running on the same PC, each session should use a unique controller ID.

  This function is an alternative to specifying the Controller ID on the command line. If this command is found anywhere in the script, it overrides the command line setting.

  If the controller ID is not set from the command line or by using this command, it has the default value 'Z'.

  ID	A single alphabetic character from 'A' to 'Z'. It is converted to uppercase before it is stored.

  Example:
   
    // Set the controller ID to 'B'
    Cntlr ( B )
  

  //Comment

    // Comment text
  

  Comments can be entered in your script command file by prefixing them on the line with //. Comments can be alone on the line, or at the end of the line after a command.

  Example:
   
    // you can put a comment on its own line ...
    Format_UV ( UV1, CHARACTER )   //... and at the end of lines
  

  Commit_Changes / Commit_Changes2

    Commit_Changes( OPT_ERROR_LABEL )
    
  Starting in version 3.1.0, the suffix-2 commands were added, and they have added a new first parameter, the ODBC data source alias:
  
    Commit_Changes2( DataSourceAlias* , OPT_ERROR_LABEL )
  

  This command performs a database COMMIT, which makes permanent the changes to the tables made in the current unit of work. It is also used to remove row locks that are automatically put in place by the database when you do a SELECT from a database.

  The classic example of the use of COMMIT is to make sure your database remains consistent after a set of changes that affect multiple tables. If you are moving stock from one warehouse to another, you want to make sure the quantity subtracted from one is added to the other before you complete the transaction. You should do an update that subtracts stock from one warehouse, and then do an update that adds stock to the other warehouse. COMMIT the changes only after the second update has worked successfully. If the second update did not work, you should do a Rollback_Changes to un-do the first update, or else some of your stock will disappear from your database even though it is actually there.

  A COMMIT will be done for you automatically at the end of the script (EndKey / EndVal / EndMatch / ...) if you have performed any database operations and have not done a Rollback_Changes to remove it. However, this is considered an error in your script, and an error message is logged.

  DataSourceAlias*	For the suffix-2 version, the required first parameter is an ODBC database alias (literal or from a user variable), as defined in a Database / DB command. The SQL will be executed against that data source.
  OPT_ERROR_LABEL	Branch to this label if a non-fatal SQL error occurs while attempting the COMMIT. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends. The label is optional; if not specified, the script will always execute the next command step.

  Example:
    // Commit changes against the single database in use by the script
    Commit_Changes( Commit_Error )
    
    // Commit changes against a specific ODBC data source alias
    Commit_Changes2( MyODBCDS, Commit_Error )
  

  Communication_Connect

    Communication_Connect( )
  

  This command requests that Personal Communications connect to the configured host system. This call does the same function as using a mouse to click on PComm's Communication-Connect menus. This command is useful as an alternative to Cycle_Session when building in session-loss handling into your scripts.

  Note that this command returns prior to the host screen re-appearing so a delay is often needed before doing any other host commands. This command may log an error "Error while doing Communication Connect", typically when the emulator session is not running at all.

  Example:
   
    // Disconnect and re-connect Personal Communications from the host
    // and then re-connect EHLLAPI
    Communication_Disconnect( )
    Delay(3000)
    Communications_Connect()
    Delay(6000)
   
    // PComm seems to require a reconnection of EHLLAPI to the session after
    // disconnect and re-connect.
    Session_Connect()
   
    // See if Session_Connect worked
    If ( SESSION_STATUS == "0" )
     {
      Log_Error("Session_Connect failed to connect HLLAPI to host session", "INFO" )
     }
  

  Communication_Disconnect

    Communication_Disconnect( )
  

  This command requests that Personal Communications disconnect from the configured host system. This call does the same function as using a mouse to click on PComm's Communication-Disconnect menus. This command is useful as an alternative to Cycle_Session when building in session-loss handling into your scripts.

  Note that this command returns prior to the host screen re-appearing so a delay is often needed before doing any other host commands. This command may log an error "Error while doing Communication Disconnect", typically when the emulator session is not running at all.

  Example:
   
    // Disconnect and re-connect Personal Communications from the host
    // and then re-connect EHLLAPI
    Communication_Disconnect( )
    Delay(3000)
    Communications_Connect()
    Delay(6000)
   
    // PComm seems to require a reconnection of EHLLAPI to the session after
    // disconnect and re-connect.
    Session_Connect()
   
    // See if Session_Connect worked
    If ( SESSION_STATUS == "0" )
     {
      Log_Error("Session_Connect failed to connect HLLAPI to host session", "INFO" )
     }
  

  Current_Dir

    Current_Dir ("String")
    Current_Dir (%EnvironmentVariable%)
  

  This command tells TC to change the current directory it is working in. This command is only performed during the compilation of the script; therefore it should not be placed within any script.

  "String"	Any string enclosed in double-quote characters. If the string contains environment variables (denoted by starting and ending percent signs (%) these environment variables will not be resolved by TC; they will be left as they are found.
  %EnvironmentVariable%	If the parameter starts and ends with percent signs (%), TC assumes it specifies one or more environment variables to be resolved. TC resolves these environment variables at compile time. If it is unable to, a compile error results.

  Example:
   
    // Change the current directory to the root directory of the C: drive
    Current_Dir("c:\")
  
    // Change the current directory to the directory indicated by the environment variable WINDIR
    Current_Dir(%windir%)
  

  Cycle_DCC/2_Export / Cycle_Mailbox

    Cycle_Mailbox()
    Cycle_DCC/2_Export()
  

  This command closes and then re-opens the DCConnect mailbox associated with the TC session. Any transactions that have not been released are now read over again. This is useful especially when sending multiple transactions to the host screen or database prior to using Commit_Changes. If the host/database goes down when some transactions have been sent to the host/database but not committed, this command lets you re-read the transactions once the host/database is back operating again. See also Multiple DCT Transactions to a Host Screen, Multi_Release_Mode, StartTimeout, and Max_Xact_Wait.

  Example:
   
    // Cycle the mailbox
    Cycle_Mailbox()
  

  Cycle_Session

    Cycle_Session ( )
    Cycle_Session (MODE)
  

  This command cycles (stop and then start, or only stop or start) the PCOMM host terminal emulation session to which this session of TC is attached. This command is intended for use in error recovery with the host application and for situations where the host is IPLed at certain times of the day.

  If you cannot determine which host screen you are on, you can cycle the session to attempt to get back to a known host screen. Your script commands that follow the Cycle_Session command will depend on how your host handles a terminal that disconnects and reconnects in this fashion. TC does not attempt any automatic log-off or log-on as a result of this command.

  MODE

  The MODE determines how Cycle_Session behaves: DOWN Brings down the session without restarting it. UP Brings up the session previously brought DOWN. No parameters at all default to a complete cycling of the session, first down, then immediately back up. The legacy parameters 3270 and 5250 are still allowed, but are not needed (TC now automatically determine the emulation type).

  Example:
   
    // Cycle the session this TC session is using.
    Cycle_Session ( )
   
    // Bring the session down, wait for 1 hour, then bring it back up
    Cycle_Session(DOWN)
    Delay (3600000)
    Cycle_Session(UP)
  

  Database / DB

    Database ( NAME)
    DB ( NAME)
    
    Database ( NAME, ALIAS)    
    DB ( NAME, ALIAS)
  

  This function is used to name the database with which a TC session will be connecting. It is an alternative to specifying the database name on the command line using the /DB parameter. In fact, it overrides the command line setting, if one is provided.

  When using version 3.1.0 and later, this function can be used multiple times to define up to 24 ODBC data sources to be used in the TC script. The first parameter is the datasource name in Windows ODBC Datasources. The second parameter is an optional override alias name by which you will refer to the data source in subsequent TC script executable commands (e.g. End_SQL2, End_Select2, Commit_Changes2, etc.). If you do not specify an alias then you will be using the actual Windows data source name in your script's executable commands (in effect, the alias is equal to the real name). By specifying an alias which is different from the actual data source name you can create multiple connections to the same data source, and thus have multiple Selects open to the same database. Specifying an alias also makes re-configuration to accomodate a change in data sources easier.

  NAME

  The database name (up to 128 characters). It must match the name of a database that has already been created under DB2 or, if DBTYPE has been set to ODBC, the database name must have been configured as a Windows ODBC data source. For more information about how to define an ODBC data source, refer to Configuring an ODBC Data Source. The database name may be enclosed in double quotes. If it is, the double quotes are removed before the name is stored.

  ALIAS

  An optional override alias name by which you will refer to the data source in subsequent TC script executable commands (e.g. End_SQL2, End_Select2, Commit_Changes2, etc.).

  Example:
   
    // Set the database name to 'STCKROOM'.  The alias for use in suffix-2 style statement will default the the DB/data source name.
    Database ( STCKROOM )
    
    // Configure two ODBC data sources with aliases
    Database ( MyProdDB, StockDB )
    Database ( AnotherDB, AnAliasforDB ) 
    
  

  DBEncryptedPW

    DBEncryptedPW( ENCRYPTED_PASSWORD, ENCRYPTION_KEY )
    
    DBEncryptedPW( ENCRYPTED_PASSWORD, ENCRYPTION_KEY, DataSourceAlias ) 
  

  This function, like DBPassword, is used to specify the password to be used when connecting to the database. But unlike DBPassword for which the password is provided in plain text, for the DBEncryptedPW command, the password is provided in encrypted format.

  The utility TCENCRYPT is used to generate the encrypted password format, given the unencrypted password and a user provided encryption key. For example, if the password is PA55W0RD and the encryption key is ABC123, the command to run on the command line is:

    TCENCRYPT PA55W0RD ABC123
  

  and the output is the encrypted password string, which is a string of hex digits that is 8 times the length of the unencrypted password:

    6926a32be07eb60bc4acb28e7dbc5d92f4b5573c14a70833ae610f8e37a35210
  

  This encrypted password would then be provided along the same encryption key to the DBEncryptedPW command in the script.

  The maximum password size is 32 characters. And the maximum key len is 256 characters.

  Because both the encrypted password and encryption key need to be provided, there is not a command line equivalent to this command like there is for the DBPassword script command. However, if DBPassword is used on the command and DBEncryptedPW is used in the scripts, the script command will override the command line value.

  The default, if neither this command nor the DBPassword command are included in the scripts, is to connect to the database using the command line value, or, if that is not provided either, the current operating system logon ID and password is used.

  If using multiple ODBC data source, this command must be used repeatedly -- once for each data source.

  ENCRYPTED_PASSWORD	This is the encrypted password generated by the TCENCRYPT utility, which is given the unencrypted password and an encryption key. The encrypted password is a constant string made up of hex digits and will be 8 times the size of the unencrypted password. The encrypted password may be enclosed in double quotes. If it is, the double quotes are removed before the password is used.
  ENCRYPTION_KEY	This the same encryption key that is passed to the TCENCRYPT utility as the second parameter when encrypting the password. An encryption key can be any string up to 256 characters. This is a constant string. The encryption key may be enclosed in double quotes. If it is, the double quotes are removed before it is used.
  DataSourceAlias	The optional data source alias to which the password will be associated. This is a constant string.

  Example:
  
    // After running the command line utility:
    //
    //   TCENCRYPT PA55W0RD ABC123
    //
    // the encrypted password that is generated is:
    //
    //   6926a32be07eb60bc4acb28e7dbc5d92f4b5573c14a70833ae610f8e37a35210
    
    // Set the database password to PA55W0RD using its encrypted form based on the key ABC123
    DBEncryptedPW ( 6926a32be07eb60bc4acb28e7dbc5d92f4b5573c14a70833ae610f8e37a35210, ABC123 )
    
    DBEncryptedPW ( 6926a32be07eb60bc4acb28e7dbc5d92f4b5573c14a70833ae610f8e37a35210, ABC123, myODBCdsAlias )
  

  DBPassword

    DBPassword( PASSWORD )
    
    Starting in version 3.1.0 the password may be associated with a ODBC data source alias:
  
    DBPassword( PASSWORD, DataSourceAlias ) 
  

  This function is used to specify the password to be used when connecting to the database. It over-rides any command line value. The default if this command is not included is to connect using the command line value, or finally the current operating system logon ID and password.

  If using multiple ODBC data source, this command must be used repeatedly -- once for each data source.

  PASSWORD	The up-to-127 character password. The password may be enclosed in double quotes. If it is, the double quotes are removed before the name is stored.
  DataSourceAlias	The data source alias to which the password will be associated. This is a constant string.

  Example:
   
    // Set the database password to 'X1Y2Z3'
    DBPassword ( X1Y2Z3 )
    
    DBPassword ( X1Y2Z3, myODBCdsAlias )
  

  DBType

    DBType ( TYPE )
  

  This function specifies the type of database support you will be using in your command scripts. There are three choices:

  • NONE

    Use if the scripts do not perform any database operations

  • DB2

    Use if you want to perform operations on an IBM DB2 database directly - instead of using ODBC to access it.

  • ODBC

    This must be used in order for TC to be able to connect to any database other than IBM DB2. However, ODBC can also be used even when the target database is IBM DB2.

  TYPE	Set to one of the values described above.

  If a database has been specified either on the command line (/DB) or in the script files (commands DB or Database) and the DBTYPE command has not been specified, then TC defaults the database type to be DB2. If no database is specified on the command line or in the scripts and no database types are specified on the command line or in the scripts, then TC defaults the database type to NONE.

  Examples:
   
    // TC should connect directly to a DB2 database
    DBType( DB2 )
   
    // TC should use ODBC to connect to a database
    DBType( ODBC )
  

  DBUserid

    DBUserID( USERID )
    
    Starting in version 3.1.0 the user may be associated with a ODBC data source alias:
  
    DBUserID( USERID, DataSourceAlias ) 
  

  This function is used to specify the user ID to be used when connecting to the database. The default if this command is not included is to connect using the current operating system logon ID. This function will over-ride any value passed on the command line.

  If using multiple ODBC data source, this command must be used repeatedly -- once for each data source.

  USERID	The up-to-127 character user ID. The name may be enclosed in double quotes. If it is, the double quotes are removed before the name is stored.
  DataSourceAlias	The data source alias to which the user ID will be associated

  Example:
   
    // Set the database user ID to 'ERPUSER1'
    DBUserID ( ERPUSER1 )
    
    // Set the database user ID to 'ERPUSER1' for a DS
    DBUserID ( ERPUSER1, myODBCDS )
  

  DB_Null_Empty

    DB_Null_Empty ( )
  

  This mode command specifies that the TC session should run in a mode where it yields an empty string when a database Select statement fetches a NULL database column value. In the database, NULL is a different value than 0 -- NULL indicates the column in that row has never been set to any value, or that it has been explicitly set to NULL. Whenever your script assigns a column value from a Select report to a user variable using Set / Append_UV_Select_Data, this mode command controls what value the user variable gets if the database says the column is NULL.

  The default is DB_Null_Space .

  Example:
   
    // Set the operational mode of this TC session: NULL database values
    // yield an empty user variable
    DB_Null_Empty()
   
    // Find out how much remains to be picked of an item on the
    // pick list.  If value is null the picking has not started
    // for this item-picklist.
    Begin_SQL()
   
       SELECT QTY_REMAINING FROM PICK_LIST
       WHERE PICK_TASK=:uvPickTask(C)
       AND ITEM=:uvItem(C)
   
    End_SQL()
   
    Perform_Fetch( No_More_Rows )
   
    Set_UV_Select_Data( uvQtyRemaining, 2 )
   
     // The "" is double-quote marks with nothing between them...
    If ( uvQtyRemaining == "" )
      Set_UV_Kbd_Data( uvAnswer, "Picking not started" )
  

  DB_Null_Space

    DB_Null_Space ( )
  

  This mode command specifies that the TC session should run in a mode where it yields a string of a single space character when a database Select statement fetches a NULL database column value. In the database, NULL is a different value than 0 -- NULL indicates the column in that row has never been set to any value, or that it has been explicitly set to NULL. Whenever your script assigns a column value from a Select report to a user variable using Set / Append_UV_Select_Data, this mode command controls what value the user variable gets if the database says the column is NULL.

  The default is DB_Null_Space .

  Example:
   
    // Set the operational mode of this TC session: NULL database values
    // yield an empty user variable
    DB_Null_Space()
   
    // Find out how much remains to be picked of an item on the
    // pick list.  If value is null the picking has not started
    // for this item-picklist.
    Begin_SQL()
   
       SELECT QTY_REMAINING FROM PICK_LIST
       WHERE PICK_TASK=:uvPickTask(C)
       AND ITEM=:uvItem(C)
   
    End_SQL()
   
    Perform_Fetch( No_More_Rows )
   
    Set_UV_Select_Data( uvQtyRemaining, 2 )
   
    If ( uvQtyRemaining == " " )
      Set_UV_Kbd_Data( uvAnswer, "Picking not started" )
  

  DB_Null_Text

    DB_Null_Text ( )
  

  This mode command specifies that the TC session should run in a mode where it yields a string '<NULL>' when a database Select statement fetches a NULL database column value. In the database, NULL is a different value than 0 -- NULL indicates the column in that row has never been set to any value, or that it has been explicitly set to NULL. Whenever your script assigns a column value from a Select report to a user variable using Set / Append_UV_Select_Data, this mode command controls what value the user variable gets if the database says the column is NULL.

  The default is DB_Null_Space .

  Example:
   
    // Set the operational mode of this TC session: NULL database values
    // yield an empty user variable
    DB_Null_Text()
   
    // Find out how much remains to be picked of an item on the
    // pick list.  If value is null the picking has not started
    // for this item-picklist.
    Begin_SQL()
   
       SELECT QTY_REMAINING FROM PICK_LIST
       WHERE PICK_TASK=:uvPickTask(C)
       AND ITEM=:uvItem(C)
   
    End_SQL()
   
    Perform_Fetch( No_More_Rows )
   
    Set_UV_Select_Data( uvQtyRemaining, 2 )
   
    If ( uvQtyRemaining == "<NULL>" )
      Set_UV_Kbd_Data( uvAnswer, "Picking not started" )
  

  Deadlock_Timeout

    Deadlock_Timeout ( MINUTES )
  

  This function can be used to change the default time that TC allows an ODBC database operation to take before assuming a deadlock has occurred. The default is 1 minute but can be set to any value from 1 minute to 60 minutes

  This function does not have any affect when communicating natively to a DB2 database (DBTYPE=DB2).

  For ODBC connections, if any one database function takes longer than the specified timeout, TC will log a message indicating it is assuming a deadlock has occurred then it will roll back any uncommitted database operations and shut down.

  For information about how to avoid deadlocks caused by the way TC scripts are written, please see ODBC Performance and Deadlocks.

  MINUTES

  Choose a number from 1 to 60 indicating the number of minutes that TC should wait for any database operation to complete before assuming a deadlock has occurred.

  Example:
   
    // Set the deadlock timeout to 5 minutes
    Deadlock_Timeout( 5 )
   
  

  Declare

    Declare( localName )
  

  Create a named local variable which has visibility only within the Start... / End... script or subroutine in which it is declared.

  TC requires that the Declare statement for a local variable must come before the first use of that user variable in the script/subroutine so that when compiling the script TC can distinguish a local variable from a mistyped global variable name.

  During execution TC will load onto the local variable stack all Declared local variables for a given script or subroutine, no matter where they are in that script/subroutine, in any of the following situations:

  • A script is started (StartMatch, StartInterval, StartKey, ...)

  • When either style of subroutine (StartSubroutine or Sub) is called. In this case any passed parameters are put onto the local variable stack before the Declared local variables.

  • A Call or Call_Subroutine command is performed to a label that is not the start of a subroutine.

  • A Goto command branches into a script or subroutine other than than one in which it resides.

  • A command with an error label (e.g. PerformFetch, Make_Data_Request, Check_Color, ...) branches to the error label - unless that error label is within the same script/subroutine.

  Note:

  In any situation where a branch or call is into the middle of a subroutine that contains parameters (allowed but not recommended), it is not permissible for any executed command to reference any of those subroutine parameters. TC will terminate after logging an appropriate error in this case. In these situations TC will put placeholders on the local variable stack for the subroutine parameters so that the Declared local variables will be set up properly. However, since the subroutine was not actually called at the beginning with parameters being passed in, those parameters are undefined and therefore cannot be accessed during execution of the subroutine in this manner.

  If a subroutine is called (causing its parameters and local variables to be put on to the local variable stack) and then a Goto command or error label branch results in control switching to another script/subroutine, the branch into the new script will cause the local variables for the new script to be put on to the stack as well - as was described above. If later on, a Return / EndSubroutine / EndSub statement is encountered, TC will properly unload from the stack, both the set of local variables from the branch as well as the set from the original subroutine call and will properly resume execution after the Call/Call_Subroutine statement that made the original subroutine call.

  localName

  The name by which the user variable will be known. This must be different from any named global user variable, any other local user variable within the current script, or, if the local user variable is declared in a subroutine, any of the parameter names in the Sub which started the definition of the subroutine.

  Local user variables have the same maximum size -- 234 characters -- as standard global user variables.

  Both Declared local user variables and parameters passed to subroutines are stored in Transaction Connection's local user variable stack array. This array has a capacity of 1024 items; your script must have no path through the code which can cause more than 1024 local user variables (Declare statements) and/or parameters in a subroutine calling stack to be encountered. For example, you can have a main StartMatch / EndMatch block which declares 50 local user variables and passes 14 of them to a subroutine, which in turn declares 50 local user variables and passes 14 to a lower level, and so on for 14 more layers deep before you run out of stack space.

  See the comments near the start of this command that describe all of the situations that result in local variables being put on to the stack.

  Example:
   
    // User variables known only in the scope of the StartMatch / EndMatch
    // and which can be passed by address (reference) to called subroutines
    StartMatch( "MOVE", TXNDATA, 0, 4 )
   
      Declare( ItemNumber )  // Item/barcode for item which moved
      Declare( Quantity )    // Qty moved
      Declare( FromLocn )    // Moved from...
      Declare( ToLocn )      // Moved to...
   
      // Extract item number from transaction record field
      Set_UV_Data_Part( ItemNumber, TXNFIELD4, 0, 0 )
   
      // ... do similiar for quantity, from and to locations
      ...
   
      // Call routine which maps item/barcode to actual item, if needed.
      // The routine overwrites the passed user variable with mapped data.
      Call MapToRealItem( ItemNumber )
   
      ... etc.
   
    EndMatch()
   
    // Map input item to actual item and return in item user variable
    Sub MapToRealItem( I/O_Item )
   
      Declare( ParsedItem )   // Parse the input to extract
                              // the actual item if needed
   
      ... logic...
   
      // Return value
      Set_UV_UV( I/O_Item, ParsedItem )
   
    EndSub
  

  Define_Large_UV_Size

    Define_Large_UV_Size( SIZE_IN_BYTES )
  

  Define the size of the large user variables. By default large user variables can hold up to 16383 bytes of data.

  The Define_Large_UV_Size command must appear in the script before any command that references a user variable.

  SIZE_IN_BYTES

  The new size for large user variables can be between 16383 bytes and 65534 bytes. Note: Memory for the actual user variable buffers, small and large, is only allocated for those user variables that are referenced in the script.

  Example:
   
    // Define large user variables to be 32,000 bytes
    Define_Large_UV_Size(32000)
   
  

  Define_On_Error_String

    Define_On_Error_String( String, native code | SQLSTATE, [ SQLSTATE | native code ]  )
  

  Define a new On Error String for use elsewhere in the script in an On_Error_Goto command. While you can use a native code value or an SQLSTATE values in the On_Error_Goto command, using an On Error String gives a better explanation of the error condition. The RC_*.INI files define On Error Strings for quite a few error conditions. However, there may be one or more error conditions not defined in those files that your script will need to handle. This command allows you to define On Error strings for these conditions.

  This command requires at least two parameters. The first is always the On Error string. The second could be a native code value (e.g. an SQLCODE if IBM DB2 is the database type) or it could be an SQLSTATE value. If desired you may use both a second and third parameter to specify both a native code value and SQLSTATE - in either order. If both codes are specified, they should both represent the same error condition. Most times you should only have to specify the SQLSTATE value.

  The assignment of an On Error String can also be set up as a group of SQLSTATE values that all start with the same set of characters. For more information about this, please see Specifying SQLSTATE values.

  For a complete discussion about how TC handles error codes, please see How TC Handles SQL Errors.

  String

  The string that will be used in one or more On_Error_Goto commands. This must start with the two characters "OE", in upper or lower case, and it cannot be longer than 32 characters. This string should be unique amongst all others defined with this command and amongst all the On Error strings that are defined in the RC_*.INI files. This string may be enclosed in double quotes. It cannot contain any commas. For a discussion of On Error Strings, please see On Error Strings.

  native code value | SQLSTATE

  Specifies the error code(s) that are to be associated with this On Error string. This may be a native code value (e.g. a DB2 SQLCODE) or it may be an SQLSTATE. If specifying a native code value, the number should be entered without any prefix. For example, the DB2 SQLCODE for a duplicate record is -803. If an SQLSTATE value, it must be preceded by the prefix SQL. You can set up the On Error string to be associated with a group of SQLSTATE values that all start with the same characters. For instructions about how to do this and for specifing SQLSTATE values in general, please see Specifying SQLSTATE values. You can specify both a native code value and SQLSTATE value as the second and third parameter if necessary. However, specifying the SQLSTATE should be sufficient, particularly when connecting to the database using ODBC.

  The Define_On_Error_String command must appear in the script before any On_Error_Goto command that references the On Error String being defined.

  Examples:
   
    // Assign OE DATETIME OVERFLOW to the SQLSTATE 22008
    Define_On_Error_String("OE DATETIME OVERFLOW", SQL22008)
   
   
    // Assign OE ARITHMETIC OVERFLOW to the SQLCODE -802 which is
    // also SQLSTATE 22003 for DB2
    Define_On_Error_String("OE ARITHMETIC OVERFLOW", -802, SQL22003)
   
   
    // Same as above plus actual use of On Error String
    Define_On_Error_String(OE ARITHMETIC OVERFLOW, "SQL22003", -802)
   
    ...
   
    StartSubroutine(xyz)
   
      On_Error_Goto(OE ARITHMETIC OVERFLOW, lblArithmeticOverflow)
      Begin_SQL
   
        // Some SQL that involves math
   
      End_SQL
   
   
      Return
   
   
    lblArithmeticOverflow:
   
      Log_Error("Overflow occurred with ...")
   
      ...
   
    EndSubroutine()
  

  Define_UVs

    Define_UVs( TOTAL_NUMBER, NUMBER_OF_LARGE )
  

  Define how many user variables are available for use and of those, how many are to be of the large size.

  The Define_UVs command must appear in the script before any command that references a user variable. If the Define_UVs command is not used, TC acts as it did in the past which is equivalent to using the command Define_UVs (250, 10).

  TOTAL_NUMBER

  The first parameter is the total number of user variables needed. This value must be larger than 20; there is no maximum - although some memory is allocated based on this value (about 16 bytes per user variable), so pick a reasonable value.

  NUMBER_OF_LARGE

  The second parameter indicates how many of the total number are to be allocated as large user variables. Large user variables can hold 16383 bytes of data; the rest of the user variables hold 235 bytes of data. The number specified for the second parameter can range from 0 up to the value specified for the first parameter. So if 0 is specified for the second parameter, all user variables will be small. If the same value is specified for both parameters, all user variables will be large. Note: Memory for the actual user variable buffers, small and large, is only allocated for those user variables that are referenced in the script. The large user variables will be the last ones in the set of user variables. For example, if you specified 200 user variables and 20 of them are large then UV1 through UV 180 will be small and UV181 through UV200 will be the large ones.

  Example:
   
    // To set up 300 user variable of which 50 are large:
    Define_UVs(300, 50)
   
    // To set up 300 user variable of which all are large:
    Define_UVs(300, 300)
   
    // To set up 300 user variable of which all are small:
    Define_UVs(300, 0)
  

  Delay

    Delay( QTY_MILLISECS* )
    Delay( KEY )
  

  This command can be used to pause the execution of your command script in one of two ways.

  • You can specify a number of milliseconds (.001 sec). The range of milliseconds is 1 to 4,294,967,294 (.001 seconds to 49.7 days).

  • Or you can specify that the execution wait indefinitely for the user to press a key. In this a pop-up is shown and the user must press Enter or click the OK button in order to continue execution.

  Note: Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a TC user variable by using the user variable's name or the notation UVn, where n ranges from 1 to 250 or the maximum defined by Define_UVs.

  If a user variable is used, that user variable may contain the word 'KEY' as well.

  Examples:
   
    // delay 1 second
    Delay( 1000 )
   
    // delay until OK is pressed
    Delay( KEY )
  

  Description

    Description ( TEXT )
  

  This command sets the text to be used as a description for the TC session that runs the script. This descriptive text is shown at the top of the window text area for the session. This makes it easier to tell which session you are observing. Use the Title to set the window title bar text.

  TEXT	Up to 75 characters to describe the function of the sessions that are processing the script.

  Example:
   
    Description ( "Verifies user ID sent DCT is in database" )
  

  Do

  Refer to the following section While (Do...While) for additional information on the DO command.

  Done

    Done()
  

  This command may be used to complete script processing without need to encounter an EndKey, etc. command.

  Example:
   
    Done()
  

  Dont_Maintain_Window_Position

    Dont_Maintain_Window_Position
  

  As of release 3.0.8d of TC (September 2012) the size and position of the TC windows is now maintained automatically based on the controller ID. This is now the default behavior. Use this new command to tell TC not to maintain its window size and position.

  This command may be placed anywhere in the script file to override the default operation of TC.

  Note that a TC session will restore the size and position of its window only after it finishes compiling the script files because the command to set the controller ID could be anywhere in the script files.

  Example:
   
    // Tell TC not to maintain the size and position of the TC window
    Dont_Maintain_Window_Position
  

  DP_Is_Comma

    DP_Is_Comma
  

  This command causes TC to use a comma for the decimal point in the output from UV_Math commands. This setting is in effect for all UV_Math usage in the script. You can put the DP_Is_Comma command anywhere in the script file. The default is to use a period for the decimal point.

  UV_Math will always accept input parameters that use either a period or a comma for the decimal point.

  Example:
   
    DP_Is_Comma
  

  Dump_UVs

    Dump_UVs
  

  If tracing is active, this command causes TC to dump the contents of all user variables, global and local, to the trace.

  Example:
   
    Dump_UVs
  

  Else

    Else
  

  This command is used in conjunction with the command If. It defines a script step or set of steps that should be executed only when the test condition of the If statement was false. See also Script Control Using If/Else.

  Example:
   
    // If user variable 1 is greater than 100.0,
    // send an error message to the terminal;
    // otherwise (the 'Else'), send an good acknowledgment
    If ( UV1 #> "100.0" )
     {
      Clear_UV( UV1 )
      Append_UV_Kbd_Data( UV1, "This value cannot exceed 100.0")
      Send_Term_UV_Data ( UV1, 1, SYNCH )
      Send_Term_VResp ( FAIL )
     }
    Else
     {
      Send_Term_VResp ( PASS )
     }
  

  Emultype

    Emultype( TYPE )
  

  This specifies the host screen emulation support product type you will be using in your command scripts.

  TYPE

  This optionally specifies the host screen emulation support. To indicate the emulation support you are using specify one of the the following keywords: PCOMM ( Personal Communications ) CM ( Communications Manager/2 (OS/2 only) ) Note 2:Support for the Talk Thru option (TT) was discontinued after version 3.1.1 of TC. If you are not going to be doing any screen emulation operations in the command scripts specify the following type: NONE If Emultype command is not used default will be NONE.

  Example:
   
    // Use Personal Communications
    // emulation support
   
    Emultype( PCOMM )
  

  End / End_TC

    End ()
    End_TC ()
  

  This command is used to end the execution of TC. The logoff script is executed, the connections to DCConnect, the database, and PCOMM are dropped, and control is returned to the operating system. If the Select cursor is open, it is automatically closed. A ROLLBACK is done on any non-committed SQL unit of work.

  No automatic transaction release is issued to DCConnect. If your script has not released the transaction, DCConnect presents the transaction again the next time TC is started.

  Any of the names for the command can be used. There are no parameters.

  Example:
   
    End()
  

  EndFunctionGroup / EndCluster

    EndFunctionGroup ( )
    EndCluster ( )
  

  This command is used to indicate the end of the script started by StartFunctionGroup / StartCluster.

  Example:
   
      EndFunctionGroup( )
  

  EndInterval

    EndInterval()
  

  This command is used to indicate the end of a time interval script to be executed at specific intervals of time during the day.

  The command StartInterval begins the definition of the script, while this command is used to end the script.

  Example:
   
    StartInterval( 60000 )
   
      // Do something once a minute....
   
    EndInterval()
  

  EndKey

    EndKey ( )
  

  This command is used to indicate the end of the script started by StartKey.

  During execution, if your script does not release the DCConnect transaction prior to encountering the EndKey command, TC automatically releases the transaction and logs an error message. If 3 automatic releases are performed in succession, an error message is logged and TC terminates.

  If an EndKey command is encountered while a non-committed SQL unit of work (for example, an Insert or Update) has been created, TC automatically COMMITs the work for you while logging an error message.

  Example:
   
      EndKey( )
  

  EndLogoff

    EndLogoff ( )
  

  This command is used to indicate the end of the Logoff script to be executed each time TC ends. The EndLogoff command terminates the script started by StartLogoff.

  Example:
   
    StartLogoff()
      Send_Host_Kbd_Data( PF12, PROBLEM )
      Send_Host_Kbd_Data( PF12, PROBLEM )
      Send_Host_Kbd_Data( PF12, PROBLEM )
      Set_Cursor( 24,7 ) // Command line
      Send_Host_Kbd_Data("Logoff", PROBLEM )
      Send_Host_Kbd_Data( ENTER, PROBLEM )
   
    PROBLEM:
   
    EndLogoff( )
  

  EndLogon

    EndLogon ( )
  

  This command is used to indicate the end of the Logon script to be executed each time TC starts. The EndLogon command terminates the script started by StartLogon.

  Example:
   
    StartLogon()
      Set_Cursor( 5,43 ) // User ID input field
      Send_Host_Kbd_Data("JUNEC", LOCKED_OR_BUSY )
      Set_Cursor( 6,43 ) // Password input field
      Send_Host_Kbd_Data("J5J5J5J", LOCKED_OR_BUSY )
      Send_Host_Kbd_Data( ENTER, LOCKED_OR_BUSY  )
      Goto Exit_logon
   
    LOCKED_OR_BUSY:
      End_TC()
   
    Exit_logon:
   
    EndLogon( )
  

  EndMatch

    EndMatch ( )
  

  This command is used to indicate the end of the command script based on the match of a character string to a piece of a transaction or other data part. The EndMatch command terminates the script started by StartMatch.

  During execution, if your script does not release the DCConnect transaction prior to encountering the EndMatch command, TC automatically releases the transaction and logS an error message. If three automatic releases are performed in succession, an error message is logged and TC terminates.

  If an EndMatch command is encountered while a non-committed SQL unit of work (for example, an Insert or Update) has been created, TC automatically COMMITS the work for you while logging an error message.

  Example:
   
    EndMatch( )
  

  End_SQL / End_SQL2 / End_Select / End_Select2

    End_SQL( OPT_ERR_LABEL )
    
  Starting in version 3.1.0, the suffix-2 commands were added, and they have added a new first parameter, the ODBC data source alias:
    
    End_SQL2( DataSourceAlias* , OPT_ERR_LABEL )
  
  In version 3.1.0e, the End_Select / End_Select2 commands were added:
  
    End_Select( OPT_ERR_LABEL )
    End_Select2( DataSourceAlias* , OPT_ERR_LABEL )
  
  

  End a free-form SQL statement area. Any references to TC user variables (e.g. :UV10 ), transaction delimited fields (:TXNFIELD3) and SQL macros (e.g. :sqlCurrentTime) are replaced with the current contents of the user variable, transaction record data or SQL text, any optional formatting specified in parentheses after these references is performed (only in the SQL statement -- the user variable is not changed) and then the statement is prepared and executed. If it is a SELECT statement, the SQL cursor will be opened and Perform_Fetch commands can be used to retrieve rows of the report.

  The End_Select / End_Select2 commands are equivalent to the End_SQL / End_SQL2 commands except that the *Select* commands assume the SQL statement should be treated like a SELECT that is attempting to return a result set - as opposed to an INSERT or UPDATE operation. This allows the use of a WITH clause at the beginning of a SELECT statement. The *SQL* commands assume the SQL is a SELECT statement only if the statement starts with the word SELECT or CALL.

  Only one SQL statement can be enclosed in a Begin_SQL / End_SQL (or any of the variations of these commands) pair. For example, an UPDATE and an INSERT must be separated into 2 free-form SQL sections.

  The suffix-2 version of these commands is required in order to work with more than 1 ODBC data source; its use is optional for single database scripts.

  DataSourceAlias*	For the suffix-2 version, the required first parameter is an ODBC database alias literal or user variable contents (as defined in a Database / DB command). The SQL will be executed against that data source.
  OPT_ERR_LABEL	Branch to this label if the database driver reports an SQL error when preparing or executing your SQL statement. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends. The label is optional; if not specified, the script will always execute the next command step.

  Example:
   
    //* Get worker first name based on badge number in
    //* transaction field 2 and branch plant stored in
    //* user variable UV1.  Both are bracketed with
    //* single quotes to make them SQL character strings
    //* as the values are inserted into the SQL string.
    //* This executes against the first database configured 
    //* in the script/via command line. 
    Begin_SQL()
   
      Select FIRST_NAME from EMPLOYEES
        WHERE BADGE_NUMBER = :TXNFIELD2(C)
        AND BRANCH_PLANT = :UV1(C)
   
    End_SQL(SQL_error)
    
    
    //* Same sql, but executed against a specific connection
    DB( oERP, "Inventory"
    DB( oWhse, "Warehouse" )
    ...
    Set_UV_Kbd_Data( gInvDS, "Inventory" )
    ...
    Begin_SQL()
   
      Select FIRST_NAME from EMPLOYEES
        WHERE BADGE_NUMBER = :TXNFIELD2(C)
        AND BRANCH_PLANT = :UV1(C)
   
    End_SQL2( gInvDS, SQL_error)
    
  
    //* The following example illustrates the use of Begin_Select / End_Select 
    //* instead of Begin_SQL / End_SQL to make sure the SQL is treated like a SELECT 
    //* command since it contains a WITH clause at the beginning and Begin_SQL / End_SQL 
    //* would not consider it to be a SELECT statement.  This example illustrates the
    //* syntax even though the WITH clause here doesn't accomplish anything that couldn't
    //* be done directly without the WITH clause.
    Begin_Select()
  
      With TempTable as 
      ( 
         select employee concat '(' concat name concat ')' as ConcatName, work_group as wg from dclib.emplgrp 
      )
      select ConcatName, WG from TempTable
  
    End_Select(SQL_error)
  
  

  EndSub / EndSubroutine

    EndSub( )
    EndSubroutine( )
  

  This command ends the definition of a subroutine script. The subroutine script is started with a command Sub or StartSubroutine, and is called with the command Call or Call_Subroutine.

  Example:
   
    EndSub( )
  

  EndTime

    EndTime()
  

  This command is used to indicate the end of a time-of-day script to be executed at a specific time each day.

  The command StartTime begins the definition of the script, while this command is used to end the script.

  Example:
   
    StartTime( 03:00:00 )
   
      Log_Error ( "It is 3:00 a.m.:  Shutting down TC for the day")
   
      End_TC()
   
    EndTime()
  

  EndTimeout

    EndTimeout()
  

  This command is used to indicate the end of the StartTimeout script to be executed each time TC times out while waiting for a transaction from DCConnect. The timeout value is set using the command Max_Xact_Wait.

  This command is useful for tasks such as shutting down TC when no transactions are available for processing.

  The command StartTimeout begins the definition of the script, while this command is used to end the script.

  Example:
   
    // A manual procedure or a COMMAND file has dialed a modem
    // to connect to headquarters, and a switched line PCOMM
    // 5250 session has been started.  As soon as all accumulated
    // DCT transactions have been transferred to the host system,
    // we want to logoff and terminate the session, which
    // will then allow the phone line to be dropped.
   
    // If no transactions are available for 2 seconds, call
    // the TIMEOUT procedure.  2 seconds is plenty of time
    // for DCConnect to retrieve any available transactions.
    Max_Xact_Wait ( 2000 )
   
    StartTimeout()
   
      Log_Error ( "Transactions completed, logging off...")
   
      End_TC()  // End_TC causes Logoff script to be executed.
   
    EndTimeout()
  

  End_UV

   
    End_UV( TargetUserVariable )
  

  End a user variable text area, substitute the current contents of referenced user variables into the fixed portions of the string, and set the target user variable with the result.

  TargetUserVariable

  The target user variable to be set with the resulting string.

  The user variable string formed between the Begin_UV and End_UV commands could be a simple message such as:

    Begin_UV()
      Error converting quantity.
    End_UV( OutMessage )
  

  You could achieve the same result using Set_UV_Kbd_Data( OutMessage, "Error converting quantity." ).

  A more elaborate usage would involve references to other user variables in order to substitute their current value into the string. References to user variables are made by prefixing the user variable's name with a colon and then adding a format specifier suffix:

    Begin_UV()
      Error converting quantity for item :ItemNumber
    End_UV( OutMessage )
  

  The format specifiers available include:

   
    (C) to format as a character string with leading and trailing single-quote marks
    (N) to format as a numeric string (any single-quotes are removed)
    (T) to format a HHMMSS value into a single-quoted time string
    (D) to format a YYMMDD value into a single-quoted date string
    (S) to format a YYMMDDHHMMSS value into a single quoted timestamp
    (X) for no formatting
   
  

  The use of a format specifier is optional, however, in situations where the name of the user variable becomes indistinguishable from the surrounding fixed text it becomes essential. Use the 'no formatting' (X) specifier in these situations, such as in bar code printer command strings where printer commands surround the user variable reference:

    Begin_UV()
      ^H200^V0524^BG03140:LicensePlate(X)^H200^V0680^L0101^S
    End_UV( PrtCmd )
  

  Add white-space and comments to the fixed text to make it more readable. Any comments, blank lines, leading and trailing spaces are stripped off the fixed string as it is compiled.

  You may want to create user variables containing special strings to be substituted into the text, such as a single space for use as a 'required blank' or a carriage-return/line feed to format the output when printed.

  Example:
   
    Declare( TargetUV )
    Declare( Var1 )
    Declare( Var2 )
    Declare( Barcode )
    Declare( aSpace )
    Declare( aCRLF )
   
    Set_UV_Kbd_Data( aSpace, " " )           //* Use to force a space character between words where a line break is included in the source file
    Set_UV_Kbd_Data( aCRLF, CRLF )           //* Use named UVs to imbed control characters such as carriage-return and line feed
   
    // Test user variables:
   
    Set_UV_Kbd_Data( Barcode, "B1234" )
   
    Set_UV_Kbd_Data( Var1, "Var1's Contents" )
    Set_UV_Kbd_Data( Var2, "Var2's Data" )
   
    Begin_UV()
   
      This is Var1:":Var1(X)" and:aSpace(X)                 // We want a space between '... and' and 'the ...' from the next line
      the text :aCRLF(X)                                    // Add carriage return, line feed
      :Var2(C) is in Var2.:aCRLF(X):aCRLF(X)                // Comments get stripped off during compile
   
      Sample Intermec printer command ^BC:Barcode(X)^T12    // Add comment to describe label construction
   
    End_UV( TargetUV )
   
    Log_Data( "OUT.DAT", TargetUV, OVERWRITE )
  

  This produces the output:

    This is Var1:"Var1's Contents" and the text
    'Var2''s Data' is in Var2.
   
    Sample Intermec printer command ^BCB1234^T12
  

  EndVal

    EndVal ( )
  

  This command is used to indicate the end of the validation file command set started by StartVal.

  During execution, if an EndVal command is encountered while a non-committed SQL unit of work (for example, an Insert or Update) has been created, TC will automatically COMMIT the work for you (while logging an error message).

  Example:
   
    EndVal( )
  

  End_WS / EndWebService

    End_WS ( )
    End_WS( "ServiceName" )
  

  This command marks the end of the section of the script (scriptlet) that will handle a specific incoming request for a web service.

  "ServiceName"

  Constant string literal that matches the incoming web service request's name. This is optional -- used for ease of reading the script code only

  Example:
  
  Name_UV( UV1, gHandle ) 
  
  // Processing Scriptlet for "ShowOrder" web service
  Start_WS ("ShowOrder", gHandle)
  
     Declare (varA)
     Declare (varB)
     Declare (outHandle)
     Declare (rc)
     Declare ( OrderID )
     Declare ( OrderDate )
     
     WS_EnterElement(gHandle,"soap:Body", 1, rc)
     
     WS_EnterElement(gHandle,"tns:ShowOrder", 1, rc)
  
     WS_GetElement (gHandle, "tns:orderID", OrderID, rc)
     
     // Create a response to the received request.
     // The web service table indicates that the response is
     // in SOAP XML format, so this automatically creates the soap:Envelope
     // as the root element and creates empty soap:Header and soap:Body
     // elements as children.
     WS_CreateResponse (gHandle, outHandle)
  
     // Navigate into soap:Body element 
     WS_EnterElement ( outHandle, "soap:Body", 1, rc )
     
     // Create a child under soap:Body
     WS_CreateElement(outHandle,"tns:ShowOrderResponse", rc)
     WS_EnterElement( outHandle, "tns:ShowOrderResponse", rc )
     
     WS_SetElement( outHandle, "tns:Result", 1, "OK", rc ) 
     
     // Send the response message
     WS_SendResponse( outHandle )
     
     WS_Cleanup( gHandle )
     WS_Cleanup( outHandle ) 
     
  End_WS( "ShowOrder" )
   
  

  Format_UV

    Format_UV( UV, field_type )
    Format_UV( UV, field_type, format )
    Format_UV( UV, REAL_NUM, total_length, fractional_length, sign_allowed)
    Format_UV( UV, strip_style, strip_char )
    Format_UV (UV, TAKE_LEADING_CHARS, numToTake*)
    Format_UV (UV, DROP_LEADING_CHARS, numToDrop*)
    Format_UV (UV, TAKE_TRAILING_CHARS, numToTake*)
    Format_UV (UV, DROP_TRAILING_CHARS, numToDrop*)
    Format_UV (UV, PAD_LEADING,  padChar,  finalLength*)
    Format_UV (UV, PAD_TRAILING, padChar,  finalLength*)
    Format_UV (UV, TAKE_MID_CHARS, start*, numToTake*)
    Format_UV (UV, DROP_MID_CHARS, start*, numToDrop*)
    Format_UV( UV, UPPER_CASE )
    Format_UV( UV, LOWER_CASE )
    Format_UV( UV, REPLACE, varOldSubString, varNewSubString )
    Format_UV( UV, ASCII_TO_EBCDIC )
    Format_UV( UV, EBCDIC_TO_ASCII )
   
  

  This command can be used to separately format the contents of a TC user variable to match the requirements of a database column type or to a specific size/style or adds/replaces/deletes characters or strings. The output of the formatting is placed back into the source user variable.

  For example, the database driver expects character data to have single quotes around it. The TC commands that require you to specify the column type (for example, Setup_Insert_Field and Update_Where, among others) already take care of formatting the data involved. When you are using free-form SQL (see Begin_SQL), you must preformat the user variables to make sure their form matches the usage in your free-form SQL.

  When in doubt about the current format of a user variable's data, use the Format_UV command; it will determine if the format is already correct and will not, for example, put additional single quotes around a string that already has them.

  You can use this command to format a user variable to specific widths, precisions, justification, and/or padding. This is useful for manipulating data to check for in Check_Screen command, formatting data to send to the host screen, and so forth.

  The field_type REAL_NUM can be used to convert a number in a value in a user variable to the format that MAPICS/XA expects real numbers to be in. Real numbers are those that can have a decimal point or a negative sign entered by the user. Given input in the format entered by the user, the REAL_NUM option of the Format_UV command rearranges the number so that it is in three sections:

  • The whole part
  • The fractional part
  • the sign position.

  The decimal point, if present, is removed.

  The value for the whole part is right justified within its section and is padded to the left with zeros. The value for the fractional part is left justified in its section and is padded to the right with zeros. The sign position contains a space if the number is positive or a negative sign if the number is negative.

  This function specifies the total length before the conversion, the number of fractional digits allowed and an indication as to whether a sign is allowed. To calculate the maximum number of whole digits allowed, start with the total length and then subtract the fractional digits. If the fractional digits allowed was not 0, subtract 1 for the decimal point. If a sign is allowed, subtract 1 more. The result is the number of digits allowed in the whole number.

  As an example, if the total length is 12, then fractional length is 3, and a sign is allowed, then the whole length is (12 - 3 - 1 - 1) = 7. This Format_UV command would have the following syntax:

    Format_UV( UV1, REAL_NUM, 12, 3, YES )
  

  With these parameters in mind, take a look at what the conversion does:

      Before conversion            After conversion
        [12345       ]               [0012345000 ]
        [-32         ]               [0000032000-]
        [54.36       ]               [0000054360 ]
        [-123456.8   ]               [0123456800-]
        [0           ]               [0000000000 ]
        [-1234567.123]               [1234567123-]
  

  Two things to note about the values above:

  • All of the values above were padded with spaces out to 12 characters before the Format_UV command was performed. This can be done with the following Format_UV command:

      Format_UV( UV1, CUSTOM_CHARACTER, -12.12 )
    

  • In all values above, the resulting data is one byte less than you started with because the decimal point is removed.

  If the number of fractional digits allowed is 0. The before and after lengths are the same.

  Format_UV also accepts format types which can be used to format data by removing characters in the beginning, middle or end of the data or by padding characters to the beginning or end of the data up to a specified length.

  UV	The TC user variable.
  field_type	For database column usage, this specifies the type of data used in the table column against which the user variable is processed (assigned, operated, or compared). This can be NUMERIC, CHARACTER, TIME, DATE, or TIMESTAMP. The type tells TC whether to put quotes around the data (CHARACTER or time/date types) and whether to add delimiters and the century to time/date types. For time/date types, the input data can be in the form sent by the terminal or it can already have delimiters in place. Data for a TIME type column must be in the form HHMMSS (as it comes from the terminal), HH:MM:SS, or 'HH:MM:SS'. Data for a DATE type column must be in the form YYMMDD (as it comes from the terminal), YYYY/MM/DD, or 'YYYY/MM/DD'. Data for a TIMESTAMP type column must be in the form YYMMDDHHMMSS (as it comes from the terminal), YYYY-MM-DD-HH.MM.SS, or 'YYYY-MM-DD-HH.MM.SS'. For general, customized formatting, use the FIELD_TYPES CUSTOM_CHARACTER or CUSTOM_NUMERIC, followed by the format string. Use CUSTOM_NUMERIC for user variable data to be interpreted as a number; otherwise, use CUSTOM_CHARACTER. If formatting a real number for MAPICS/XA, use the keyword REAL_NUM for the field type.
  format	Optional format string, specifying the width and precision, justification, and padding of the output for the column. The format string has 3 optional subsections: [flags][width][.precision] where: flags Can be one or more of: - Left-justify the result within the field width (default is right-justify). + Prefix the output value with a sign (+ or -) if the output value is of a signed type. ' ' (blank) Prefix the output values with a blank if the output value is signed and positive. The "+" flag overrides the blank flag if both appear, and a positive signed value will be output with a sign. width Is a non-negative decimal integer controlling the minimum number of characters in the output. If the number of characters in the output is less than the specified width, blanks are added on the left or right (depending on whether the "-" flag is specified) until the minimum width is reached (not useful for left-justified numbers). The width never causes a value to be truncated; if the number of characters in the output value is greater than the specified width, or the width is not given, all characters of the value are in the output (subject to the precision specification). .precision Is a non-negative decimal integer, preceded by a period, that specifies the number of characters to be in the output or the number of decimal places. Unlike the width specification, the precision can cause truncation of the output value or rounding of a floating-point value. The effect of the precision and the default when no precision is specified depends on the type of data being formatted: Numbers The precision specifies the number of digits after the decimal point. If a decimal point appears, at least one digit appears before it. The value is rounded to the appropriate number of digits. The default precision is zero. Character Strings The precision specifies the maximum number of characters in the output. Characters in excess of the precision are not in the output. The default is that all characters are used. The basic type of FORMAT string simply re-shapes the data already in the user variable. An advanced form of the FORMAT string can be used that can simplify your scripts by combining several user variable manipulations into one step. This format uses the flags, width, and precision as described above, but you can also specify accompanying text, and you must specify a prefix % character and suffix of either a 's' for an input user variable containing text data, or 'f' when it contains a numeric value (either integer or real-number). See the Example that follows.

  total_length	Indicates the starting total length of the real number field. This must exactly match the length of the data in the specified user variable. The data may be padded with blanks, but that length including the blanks must match the value specified for this parameter. After formatting, the length of the user variable data is one byte less than the value specified here - unless 0 fractional digits are allowed. If no fractional digits are allowed, the before and after lengths of the user variable are the same. The total length includes space for the whole part of the number, the fractional part of the number, the decimal point (if allowed) and the sign (if allowed).
  fractional_length	Indicates the maximum number of fractional digits that can be in the value in the user variable before formatting begins. This value then determines how the output should be formatted. This value has to be at least two less than the total length to allow for the decimal point and one whole digit. If a sign is allowed, this value must be one additional character smaller.
  sign_allowed	Indicates if a sign is allowed in the user variable before formatting begins. It also dictates whether or not the output will have a sign position. Valid values for this field are NO or YES.
  strip_style	The indicates one of the following strip characters types: STRIP_LEADING_CHARS Strip leading characters if they match the strip character. STRIP_TRAILING_CHARS Strip trailing characters if they match the strip character. STRIP_ALL_CHARS Strip all characters that match the strip character.
  strip_char	The strip_char is a quoted character (i.e. "0", " ", etc.) or a defined value such as CR, LF, COMMA, FF, VT, SI, BEL, HT, or SO (e.g. characters which are difficult/impossible to input with a text editor or which have special meaning to the TC source file parser). For a complete list of defined constant character values please see Append_UV_Kbd_Data / Append
  ASCII_TO_EBCDIC	Tells TC to convert to EBCDIC all characters in the specified user variable. TC assumes all characters in the buffer are ASCII to begin with but has no way of verifying that.
  EBCDIC_TO_ASCII	Tells TC to convert to ASCII all characters in the specified user variable. TC assumes all characters in the buffer are EBCDIC to begin with but has no way of verifying that.
  LOWER_CASE	Use this as the second parameter to tell TC to convert all of the lower case letters in the specified user variable to lower case.
  UPPER_CASE	Use this as the second parameter to tell TC to convert all of the lower case letters in the specified user variable to upper case.
  REPLACE	Tells TC to convert all instances in the specified user variable of the string in user variable varOldSubString with the string in user variable varNewSubString. If the new string is longer than the old string then you may find that none/not all of the instances of the old string are changed if that would have resulted in overflowing the allowed size in the specified user variable.
  TAKE_LEADING_CHARS	Use this as the second parameter to truncate the the user variable to a certain number of characters. The third parameter specifies the number of characters of the current data to keep; the rest are discarded. The third parameter can be a constant or a user variable that contains the number of characters. If the current length of the user variable is less than the length specified, the user variable is not changed.
  TAKE_TRAILING_CHARS	Similar to TAKE_LEADING_CHARS except that TC starts counting characters from the current end of the user variable.
  DROP_LEADING_CHARS	Use this as the second parameter to truncate the user variable by specifying a certain number of characters to remove from the beginning of the user variable. The third parameter specifies the number of characters to remove. The third parameter can be a constant or a user variable that contains the number of characters. If the actual size of the user variable data is less than or equal to the length specified, the final result is an empty user variable.
  DROP_TRAILING_CHARS	Similar to DROP_LEADING_CHARS except that TC starts counting characters from the current end of the user variable.
  PAD_LEADING	Use this as the second parameter to tell TC to pad the beginning of the user variable data to a specific length using a specific pad character. The padChar is a quoted character (i.e. "0", " ", etc.) or a defined value such as CR, LF, COMMA, FF, VT, SI, BEL, HT, or SO (e.g. characters which are difficult/impossible to input with a text editor or which have special meaning to the TC source file parser). For a complete list of defined constant character values please see Append_UV_Kbd_Data / Append The fourth parameter, finalLength, specifies the length that the user variable should be after adding the pad characters. However, if the user variable is already equal to or greater than the specified finalLength, it is not changed.
  PAD_TRAILING	Similar to PAD_LEADING except that TC adds the padChar to the end of the current data instead of the beginning.
  TAKE_MID_CHARS	Use this as the second parameter to truncate the current user variable data by taking a specified number of characters from the middle and discarding the rest. This is equivalent to using the DROP_LEADING_CHARS option followed by the TAKE_LEADING_CHARS option. The third parameter, the specified start position, can be a constant or a user variable and is a 0-based value; the first character of the user variable is position 0, the second character is position 1, ... The fourth parameter, the specified length, which can be a constant or a user variable, indicates how many character to take from the middle - and as a result will be the final length of the user variable unless the start or length goes past the end of the data. If the start is past the current end of the data, the user variable is in effect cleared. A message is logged in this situation. If the specified length is 0 or the number of characters available starting at the start position is less than the specified length, TC uses the actual number of characters that are available from the starting position. This is equivalent to having used the DROP_LEADING_CHARS option with the third parameter being the start parameter. If the start is 0, this is equivalent to having used the TAKE_LEADING_CHARS option with the third parameter being the 'numToTake' parameter.
  DROP_MID_CHARS	Use this as the second parameter to remove characters from the middle of the user variable. The third parameter, the specified start position, can be a constant or a user variable and is a 0-based value; the first character of the user variable is position 0, the second character is position 1, ... The fourth parameter, the specified length, which can be a constant or a user variable, indicates how many character to remove from the middle. If the start is past the current end of the data, the user variable is not changed. A message is logged in this situation. If the specified length is 0 or the number of characters available starting at the start position is less than the specified length, TC uses the actual number of characters that are available from the starting position. This is equivalent to having used the TAKE_LEADING_CHARS option with the third parameter being the start parameter. If the start is 0, this is equivalent to having used the DROP_LEADING_CHARS option with the third parameter being the 'numToDrop' parameter.

  Example:
   
    // Format UV1 to be used as a database character column value
    Format_UV ( UV1, CHARACTER )
   
    // Get transaction field 1 from the transaction record and
    // format it to a fixed length of 25 character, using space
    // characters padded on the right to create the needed length.
    Clear_UV( UV2 )
    Append_UV_Xact_Data( UV2, TXNFIELD1, 0, 0 )
    Format_UV( UV2, CUSTOM_CHARACTER, -25.25 )
   
    // Specify the complete format string yourself so that additional
    // text can be used.
    // Format the number in a user variable into some descriptive text
    Format_UV( UV3, CUSTOM_NUMERIC, "Current hours worked = %5.2f" )
   
    // Format a real number that is 12 characters on input, can have up
    // to 3 fractional digits and can include a sign.  For example:
    // if UV4 starts as "-12.3" it becomes "0000012300-".
    Format_UV(UV4, REAL_NUM, 12, 3, YES)
   
    // The result of this operation is UV1 set to "1234567890"
    Set_UV_Kbd_Data(UV1, "1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ")
    Format_UV(UV1, TAKE_LEADING_CHARS, 10)
   
    // The result of this operation is UV1 set to "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
    Set_UV_Kbd_Data(UV1, "1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ")
    Format_UV(UV1, DROP_LEADING_CHARS, 10)
   
    // The result of this operation is UV1 set to "QRSTUVWXYZ"
    Set_UV_Kbd_Data(UV1, "1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ")
    Format_UV(UV1, TAKE_TRAILING_CHARS, 10)
   
    // The result of this operation is UV1 set to "1234567890ABCDEFGHIJKLMNOP"
    Set_UV_Kbd_Data(UV1, "1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ")
    Format_UV(UV1, DROP_TRAILING_CHARS, 10)
   
    // The result of this operation is UV1 set to "000123.456"
    Set_UV_Kbd_Data(UV1, "123.456")
    Format_UV(UV1, PAD_LEADING, 10)
   
    // The result of this operation is UV1 set to "123.456000"
    Set_UV_Kbd_Data(UV1, "123.456")
    Format_UV(UV1, PAD_TRAILING, 10)
   
    // The result of this operation is UV1 set to "ABCDEFGHIJ"
    Set_UV_Kbd_Data(UV1, "1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ")
    Format_UV(UV1, TAKE_MID_CHARS, 10, 10)
   
    // The result of this operation is UV1 set to "1234567890KLMNOPQRSTUVWXYZ"
    Set_UV_Kbd_Data(UV1, "1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ")
    Format_UV(UV1, DROP_MID_CHARS, 10, 10)
   
    // Convert all lower case letters in UV4 to upper case
    Format_UV(UV4, UPPER_CASE)
    
    // Convert all single quotes with 2 single quotes (for SQL transparency)
    Declare( SingleQuote ) 
    Declare( TwoSingleQuotes )
    Set_UV_Kbd_Data( SingleQuote, "'" ) 
    Set_UV_Kbd_Data( TwoSingleQuotes, "''" ) 
    Format_UV( varDescr, REPLACE, SingleQuote, TwoSingleQuotes ) 
   
  

  Forward_Data_Request

    Forward_Data_Request ( APPLICATION_NAME* )
    Forward_Data_Request ( APPLICATION_NAME*, ERROR_LABEL)
  

  This function allows the TC session to specify the current data request be forwarded to another application for servicing. This function is valid only if running in DATA_REQUEST mode.

  The forward request is actually routed through DCConnect who makes sure it gets to the specified target application.

  The target application must be one that is currently registered with DCConnect to handle data requests. It can even be the same application that has just read the request (the current TC session). In this case the request is added to the end of the list of outstanding requests for this application.

  Once a data request has been fowarded that request is considered by TC to have been processed by the script and it is therefore no longer valid to use the Reply_To_Data_Request or Forward_Data_Request commands until the next request is received.

  APPLICATION_NAME*	The name of the target application that should receive the data request. It must be one that is currently registered with DCConnect. The application name can be specified either as a string enclosed in double quotes or it may be specified as a particular user variable that will contain the application name at run time.
  ERROR_LABEL	The default label to branch to in the event of an error. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control returns to the next command when the subroutine ends. The label is optional; if not specified, the script always execute the next command step.

  Example:
   
    Name_UV( UV242, REPLY_BUFFER )
   
    // Forward the stock room data request to one of two applications
    // based on
   
    StartMatch ( "STCKRM", TXNDATA, 0, 6 )
   
      if (TXNFIELD2 = "A")
   
         Forward_Data_Request("HANDLER_A", Forward_Failed)
   
      else
   
         Forward_Data_Request("HANDLER_B", Forward_Failed)
   
      Goto EndStckRmm
   
  Forward_Failed:
   
      // ... steps to set up response in the REPLY_BUFFER
      // ... to tell originator that the forward failed.
   
      Reply_To_Data_Request( REPLY_BUFFER )
   
  EndStckRm:
   
   
    EndMatch
  

  Get_Application_List

    Get_Application_List( LIST_UV, COUNT_UV )
  

  Get a comma-separated list of the valid applications in the DCConnect configuration. There are no spaces between the application names in the returned list, only commas. Also returned is the number of names in the list.

  By default, if the DCConnect Server is not running when this command is issued, TC will terminate. However, the command No_Terminate_From_DCConnect can be used to tell TC not to shut down in this case. Instead, the next command will be performed and the data part LAST_ERROR will be set to an error value. The list count will also be set to 0 in this case.

  If there is any chance that the list of names could exceed the size of a small TC user variable - 235 bytes - then be sure to use a large user variable for the first parameter.

  LIST_UV	The TC user variable into which the application list will be stored if the DCConnect Server is running.
  COUNT_UV	The TC user variable which will contain the number of names in the list when the command completes. If an error occurs, this will be set to 0.

  Example:
   
    ...
    Name_UV(NEXT_UV, uvApplicationList)
    Name_UV(NEXT_UV, uvApplicationCount)
    Name_UV(NEXT_UV, uvApplicationName)
  
    ...
  
    Get_Application_List ( uvApplicationList, uvApplicationCount )	
  
    // Start the first application in the list
    if (uvApplicationCount #> 0)
    {
      Parse_UV (uvApplicationList, uvApplicationName, ",", uvApplicationList)
  
      Start_Application ( uvApplicationName )
    }
  
  

  Get_Cursor

    Get_Cursor( ROW_UV, COL_UV )
  

  This command is used to get the host screen cursor position and store the row and column values in 2 specified TC user variables. The upper-left corner of the display is row 1, column 1.

  Note:

  TC assumes that your PCOMM emulator session is configured for 80-column operation. If you are using any other size, use the Screen_Width command to tell TC the proper number of columns.

  ROW_UV	The TC user variable in which to store the current host cursor row. TC will automatically clear the user variable before storing the row number.
  COL_UV	The TC user variable in which to store the current host cursor column. TC will automatically clear the user variable before storing the column number.

  Example:
   
    // Get cursor position, then do recovery if we are not in column 1, any row
    Get_Cursor( UV1, UV2 )
    If ( UV2 #<> 1 )
      Call_Subroutine( NOT_IN_RIGHT_COLUMN )
  

  Get_DBType

    Get_DBType( targetUV, DataSourceAlias* )
  

  Get the type of the underlying database associated with a ODBC database alias. While the DBType was used to set the generic 'ODBC' value, this function will get a string such as 'DB2', 'SQL SERVER', or 'ORACLE' based on the ultimate database engine type.

  Use this function instead of the 'DBTYPE' data part when there is more than one data source configured.

  targetUV	The TC user variable in which the length is stored. Any data that was in this user variable will be cleared out first.
  DataSourceAlias*	The ODBC data source alias (literal, or as contents of a user variable) created in a Database / DB statement.

  Example:
   
    Get_DBType( InventoryDBType, myInvDB ) 
   
  

  Get_DCConnect_Status

    Get_DCConnect_Status( STATUS_UV )
  

  Get the status of the DCConnect Server. The value returned in the specified user variable will be one of the following:

  0 =	DCX_NO_ERROR	DCConnect Server is running.
  -2 =	DCX_NOT_RUNNING	DCConnect Server is not running.
  -3 =	DCX_SHUTDOWN_IN_PROGRESS	DCConnect Server is shutting down.
  -4 =	DCX_STARTING_UP	DCConnect Server is starting up.

  This command corresponds to the DCConnect API, DcxIsAlive.

  STATUS_UV

  The TC user variable into which the DCConnect status will be returned. See above for the possible values for the status.

  Example:
   
    ...
    Declare( uvDCCStatus )
    ...
  
    Get_DCConnect_Status ( uvDCCStatus )	
  
    // If the server is running, do some work
    if (uvDCCStatus #= 0)
    {
      // Do something that requires the server to be running
  
      ...
    }
  
  

  Get_Job_List

    Get_Job_List( LIST_UV, COUNT_UV )
  

  Get a comma-separated list of the valid jobs in the DCConnect configuration. There are no spaces between the job names in the returned list, only commas. Also returned is the number of names in the list.

  By default, if the DCConnect Server is not running when this command is issued, TC will terminate. However, the command No_Terminate_From_DCConnect can be used to tell TC not to shut down in this case. Instead, the next command will be performed and the data part LAST_ERROR will be set to an error value. The list count will also be set to 0 in this case.

  If there is any chance that the list of names could exceed the size of a small TC user variable - 235 bytes - then be sure to use a large user variable for the first parameter.

  LIST_UV	The TC user variable into which the job list will be stored if the DCConnect Server is running.
  COUNT_UV	The TC user variable which will contain the number of names in the list when the command completes. If an error occurs, this will be set to 0.

  Example:
   
    ...
    Name_UV(NEXT_UV, uvJobList)
    Name_UV(NEXT_UV, uvJobCount)
    Name_UV(NEXT_UV, uvJobName)
  
    ...
  
    Get_Job_List ( uvJobList, uvJobCount )	
  
    // Get the first job in the list
    if (uvJobCount #> 0)
    {
      Parse_UV (uvJobList, uvJobName, ",", uvJobList)
  
      ...
    }
  
  

  Get_Length

    Get_Length( UV, DATA_PART )
  

  Store in one user variable the length of another user variable or other data part. This can be very userful for parsing portions of data fields. For example, having obtained the length of a particular field, you can decrement that length value and then use the result to extract part of the beginning or part of the end of the field. See the examples below.

  UV	The TC user variable in which the length is stored; not to be confused with the user variables resident in the data collection terminals. Any data that was in this user variable will be cleared out first.
  DATA_PART	This specifies one of various predefined parts of the terminal transaction or other information that becomes part of the data appended to the target user variable. The predefined parts are listed in Data Parts. The data parts that are valid vary depending on whether the TC session is currently running in transaction, validation or data request mode.

  Example:
   
    // Get the last 3 characters from TXNFIELD6 and put them into UV50:
    Get_Length ( UV10, TXNFIELD6 )
    UV_Math( UV10, -, 3 )
    Set_UV_Xact_Data( UV50, TXNFIELD6, UV10, 3 )
   
   
    // Get all but the last character of UV13 and put them into UV50:
    Get_Length ( UV10, UV13 )
    UV_Math( UV10, -, 1 )
    Set_UV_Data_Part( UV50, UV13, 0, UV10 )
  

  Get_Mailbox_List

    Get_Mailbox_List( LIST_UV, COUNT_UV )
  

  Get a comma-separated list of the valid mailboxes in the DCConnect configuration. There are no spaces between the mailbox names in the returned list, only commas. Also returned is the number of names in the list.

  By default, if the DCConnect Server is not running when this command is issued, TC will terminate. However, the command No_Terminate_From_DCConnect can be used to tell TC not to shut down in this case. Instead, the next command will be performed and the data part LAST_ERROR will be set to an error value. The list count will also be set to 0 in this case.

  If there is any chance that the list of names could exceed the size of a small TC user variable - 235 bytes - then be sure to use a large user variable for the first parameter.

  LIST_UV	The TC user variable into which the mailbox list will be stored if the DCConnect Server is running.
  COUNT_UV	The TC user variable which will contain the number of names in the list when the command completes. If an error occurs, this will be set to 0.

  Example:
   
    ...
    Name_UV(NEXT_UV, uvMailboxList)
    Name_UV(NEXT_UV, uvMailboxCount)
    Name_UV(NEXT_UV, uvMailboxName)
  
    ...
  
    Get_Mailbox_List ( uvMailboxList, uvMailboxCount )	
  
    // Get the first mailbox in the list
    if (uvMailboxCount #> 0)
    {
      Parse_UV (uvMailboxList, uvMailboxName, ",", uvMailboxList)
  
      ...
    }
  
  

  Get_Term_List / Get_Terminal_List

    Get_Term_List( LIST_UV, COUNT_UV )
    Get_Term_List( LIST_UV, COUNT_UV, JOB_NAME* )
  

  Get a comma-separated list of the valid terminals in the DCConnect configuration. If a job name is specified as the optional third parameter, then the terminal list returned will be limited to those terminals that are assigned to the specified job. There are no spaces between the terminal names in the returned list, only commas. Also returned is the number of names in the list.

  By default, if the DCConnect Server is not running when this command is issued, TC will terminate. However, the command No_Terminate_From_DCConnect can be used to tell TC not to shut down in this case. Instead, the next command will be performed and the data part LAST_ERROR will be set to an error value. The list count will also be set to 0 in this case.

  If there is any chance that the list of names could exceed the size of a small TC user variable - 235 bytes - then be sure to use a large user variable for the first parameter.

  Note: Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "15", "ShippingMailbox", and so forth) or as the current value of a TC user variable by using the user variable's name or the notation UVn, where n ranges from one to 250 or the maximum defined by Define_UVs.

  LIST_UV	The TC user variable into which the terminal list will be stored if the DCConnect Server is running.
  COUNT_UV	The TC user variable which will contain the number of names in the list when the command completes. If an error occurs, this will be set to 0.
  JOB_NAME*	Optional job name; if specified, the list of terminals is restricted to those terminals that are assigned to the specified job. The job name must be a valid job in the DCConnect configuration and case-sensitivity matters.

  Example:
   
    ...
    Name_UV(NEXT_UV, uvTerminalList)
    Name_UV(NEXT_UV, uvTerminalCount)
    Name_UV(NEXT_UV, uvTerminalName)
  
    Name_UV(NEXT_UV, uvJobList)
    Name_UV(NEXT_UV, uvJobCount)
    Name_UV(NEXT_UV, uvJobName)
  
    ...
  
    Get_Term_List ( uvTerminalList, uvTerminalCount )	
  
    // Get the first terminal in the list
    if (uvTerminalCount #> 0)
    {
      Parse_UV (uvTerminalList, uvTerminalName, ",", uvTerminalList)
  
      ...
    }
  
  
    // Or get a terminal list for a specific job
    Get_Job_List ( uvJobList, uvJobCount)
    if (uvJobCount #> 0)
    {
      Parse_UV (uvJobList, uvJobName, ",", uvJobList)
  
      Get_Term_List ( uvTerminalList, uvTerminalCount, uvJobName )	
  
      ...
    }
     
  
  

  Get_Term_UV_Data / Get_Named_Term_UV_Data / Get_Terminal_UV_Data / Get_Named_Terminal_UV_Data

    Get_Term_UV_Data     ( UV, TERMUV )
    Get_Terminal_UV_Data ( UV, TERMUV )
  
    Get_Named_Term_UV_Data     ( TERM_NAME, UVn, TERMUV* )
    Get_Named_Terminal_UV_Data ( TERM_NAME, UVn, TERMUV* )
  

  Get the current value of user variable at a data collection terminal (DCT) and copy it to a TC user variable. The data is retrieved from the same terminal from which the current transaction or validation request originated. This variation will not work if running in Data Request mode.

  Use the Get_Named_Term_UV_Data variation if you want to specify a DCT other than the current terminal. This is useful, for example, if you want to periodically read a piece of data from many terminals for use in some type of report.

  Note:

  1. 7525 and 7527 terminals do not support this function.

  2. Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a TC user variable by using the variable's name or the notation UVn, where n ranges from 1 to 250 or the maximum defined by Define_UVs.

  TERM_NAME	Used only with the Get_Named_Term... version, this provides the name of the target data collection terminal. The TERM_NAME is always specified as the current value of a user variable (not as a constant string).
  UV	The TC user variable.
  TERMUV*	The user variable number on the DCT.

  Example:
   
    // Copy to TC user variable 1 from the current terminal's
    // user variable 10
    Get_Term_UV_Data( UV1, 10 )
   
    // Copy to TC user variable 1 from terminal LOOM_01B's
    // user variable 10
    Append_UV_Kbd_Data( UV30,"LOOM_01B")
   
    ...
   
    Get_Named_Term_UV_Data( UV30, UV1, 10 )
  

  Goto

    Goto label
  

  This command transfers control to the command following the referenced label. It is possible but not recommended to transfer control out of the current Start / End script or out of the function group block.

  Note: Going to a label inside a set of braces belonging to an If or Else statement may yield incorrect execution (or lack thereof) of subsequent commands in the script. For predictable results, always branch to labels outside any sets of braces.

  Example:
   
    Goto SQL_Error_Label
  

  If

      If ( DATA_PART_A(START, LENGTH)  COMPARE  DATA_PART_B(START, LENGTH) )
      If ( "String" | NumericConstant        COMPARE  DATA_PART_B(START, LENGTH) )
      If ( DATA_PART_A(START, LENGTH)  COMPARE  "String" | NumericConstant )
   
      If ( DATA_PART_A           COMPARE  DATA_PART_B )
      If ( "String" | NumericConstant  COMPARE  DATA_PART_B )
      If ( DATA_PART_A           COMPARE  "String" | NumericConstant )
   
      If ( DATA_PART_A, START, LENGTH,  COMPARE,  DATA_PART_B, START, LENGTH )
      If ( "String" | NumericConstant,        COMPARE,  DATA_PART_B, START, LENGTH )
      If ( DATA_PART_A, START, LENGTH,  COMPARE,  "String" | NumericConstant )
   
    And/Or/Not logic operators can be used to create more complex logic
    operations.  If we let C1, C2, ... stand for one of the ways of specifying a
    single comparison operation shown above, then the following examples show how
    multiple logic operations can be performed in a single If statement:
   
      If (NOT(C1))
      If (!  (C1))
      If ((C1) AND (C2))
      If ((C1) &&  (C2))
      If ((C1) &   (C2))
      If ((C1) OR  (C2))
      If ((C1) ||  (C2))
      If ((C1) |   (C2))
      If ((C1) AND NOT ((C2) OR (C3 AND C4)))
      ...
   
  

  The first 6 syntax definitions shown above are allowed if you are using at least fix pack E for the 1.40 version of TC.

  The use of the AND / OR / NOT logic operators are allowed only if you are using a version of TC built in November 2002 or later.

  In the second group of 3 syntax definitions shown above, the START and LENGTH values are assumed to both be 0.

  A conditional If statement is one that evaluates the contents or values of two pieces of data and compares them, resulting in the execution or skipping of the next step or steps in the script file. The two pieces of data that are compared can independently be:

  • User variable
  • Any data part
  • A literal string constant enclosed in double quotes. As of version 3.1.0d, maximum string length is 128 bytes; prior to that it was 64 bytes.
  • A numeric constant which does not have to be enclosed in double quotes and which can be any base 10 number, optionally having a leading negative sign and optionally having a decimal point.

  The comparison's logical form is:

    A comparison B
      Step to execute if above is TRUE
   
    Following Step
  

  The A and B user variables are evaluated at runtime based on the source of data you specified in your If command. The comparison (for example, =, >, !=, and so forth) of the two user variables is made, and if it was TRUE, the following steps in your script are executed at runtime. If the comparison is false, the next steps are skipped and execution continues at the following step.

  Numeric comparisons are done as follows (using the rules of the C function atof):

  • Any leading white space is skipped
  • All valid numeric characters (including decimal point, plus or minus sign and an 'e' or 'E' as part of an exponent part) after that leading white space are considered part of the number - up to the first non-numeric character or the end of the data.
  • Once the first non-numeric character is encountered, it and all following characters are simply ignored, the first valid numeric part is evaluated as if the rest of the data did not exist.
  • If no valid number is found, the result is evaluated as 0.
  Non-numeric comparisons are case-sensitive (like the C function strcmp); so lower case letters are treated differently from upper case letters.

  The use of AND / OR / NOT logic operators (and their equivalents &&, &, ||, |, !) shown above allow you to perform and link multiple comparison and logic operations in a single If statement. For more information about what syntax rules must be followed when using these operators and how TC processes these statements, please see Using AND, OR and NOT operators in If and While Statements.

  The If statement can be used in conjunction with the command Else. See also Script Control Using If/Else for discussion and examples of using If, Else, and enclosing braces ({ }) to control the flow of your script.

  DATA_PART_A	This specifies one of various predefined parts of the terminal transaction or other information that will become the string used for the A side of the comparison. The parts are listed in Data Parts. The data parts that are valid vary depending on whether the TC session is currently running in transaction, validation or data request mode.
  START	The starting position within the transaction data part. 0 is the beginning of the data.
  LENGTH	The length of data to use from the data part, starting at the START position. Refer to Data Parts for the meaning of a 0 length for a given data part. It may be ignored, it may mean return no data or it may mean take all data from the START position.
  "String"	The DATA_PART/START/LENGTH parameters for either the A or B sides of the comparison can be omitted and replaced with a literal string presented in double-quote marks or a NumericConstant (see below).
  NumericConstant	Numeric constants do not have to be enclosed in double quotes and can be any base 10 number, optionally having a leading negative sign and optionally having a decimal point.
  COMPARE	Logical comparison operator for the two values. Although the data coming from terminals or from the database is always in character string form inside TC, you can tell TC to perform the comparison treating the values either as character strings or as numeric values, depending on what the values represent in your application. Numbers can be integers or real numbers (for example, 12, 5.87, -200.6). Comparisons as strings are symbolized in the command format as follows: Equal: == or = Greater Than: > Greater Than or Equal: >= or => Less Than: < Less Than or Equal: <= or =< Not Equal: <> or != Comparisons as numeric values are input similarly, but with a leading # symbol to signify that numbers are involved: Equal: #== or #= Greater Than: #> Greater Than or Equal: #>= or #=> Less Than: #< Less Than or Equal: #<= or #=< Not Equal: #<> or #!=
  DATA_PART_B	Same definition as DATA_PART_A.
  START	Starting character for string B (see DATA_PART_A).
  LENGTH	Length of source string to use for string B (see DATA-PART_A).

  Examples:
   
    // If UV1 equals UV2 goto recovery routine
    If ( UV1 == UV2 )
      Goto Same_Badge_Read
   
    // If time from transaction timestamp is greater than 120000
    // (noon) then send user message
    If ( TIME(0, 6) >  "120000" )
      Send_Term_UV_Data( UV1, 10, ASYNCH)
   
    // If time from transaction timestamp is greater than 120000
    // (noon) or a certain flag is set then send user message
    If ((TIME(0, 6) >  "120000") || (uvAlwaysSend == "TRUE"))
      Send_Term_UV_Data( UV1, 10, ASYNCH)
   
    // If the row or column are out of range, goto error
    if ((uvRow #< 1) OR (uvRow #> 16)  OR   // Dimensions of
        (uvCol #< 1) OR (uvCol #> 20))      // terminal are 16x20
      Goto InvalidDimensions
   
    // Use reverse logic of previous example
    if (NOT ((uvRow #< 1) OR (uvRow #> 16)  OR   // Dimensions of
             (uvCol #< 1) OR (uvCol #> 20))      // terminal are 16x20
      Goto ValidDimensions
   
    // Since !(A | B | C | D) is equivalent to !A & !B & !C & !D we could also use:
    if (!(uvRow #< 1) && !(uvRow #> 16)  &&   // Dimensions of
        !(uvCol #< 1) && !(uvCol #> 20))      // terminal are 16x20
      Goto ValidDimensions
   
  

  Imbed

    Imbed ( FILENAME )
  

  Imbed another text file at this point in the script as the script is compiled.

  Note:

  If you use the IMBED command frequently, you may find at some point you would like to create a single listing file that includes all of the imbedded files. This can make it easier to search through your scripts or to analyze them. New with fix pack D of version 1.4.0 is a utility, Using the Utility IMBEDSCR.EXE to Create a Single Listing File, that can be used to create this listing file.

  FILENAME

  The name of the file to be imbedded at this point. Specify a full drive and path name if the file is not in TC's working directory (defined by the environment variable TC2). The filename parameter may contain one or more environment variables which are denoted by their starting and ending percent signs (%). TC will resolve these environment variables at compile time.

  Example:
   
    StartLogon()
   
      // Insert a common logon routine here.
      Imbed( LOGON_C.TXT )
   
    EndLogon()
  

  Initiate_Term_Event / Initiate_Terminal_Event

    Initiate_Term_Event ( TERMNAME_UV, EVENT_ID )
    Initiate_Term_Event ( TERMNAME_UV, EVENT_ID, ERR_LABEL )
  

  Initiates a transaction program (terminal event) on the specified terminal.

  TERMNAME_UV	User variable containing the name of the terminal on which the transaction program should be initiated.
  EVENT_ID	The transaction program event ID to be started on the specified terminal. The list of valid transaction identifiers is shown in StartKey.
  ERR_LABEL	An optional label to branch to when TC encounters an error when trying to send the command to the DCT. For example, an RF terminal may have moved out of range or may have been turned off by the operator. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends.

  Example:
   
    // Start the transaction program bound to the PF1 event ID on terminal BackDock23
    Set_UV_Kbd_Data (uvTerminalName, "BackDock23");
    Initiate_Term_Event (uvTerminalName, PF1, FailedToStart)
  

  Insert_DB_Table

    Insert_DB_Table( QUALIFIER.TABLE_NAME* )
  

  This is the first command of the series required to INSERT a row (record) into a database table. See also Setup_Insert_Field and Perform_Insert, and the example Inserting a Record into a Table.

  *The parameter can be specified as a quoted or unquoted string, a user variable, or a data part. Prior to version 3.1.0e, this could only be a quoted or an unquoted string.

  Note:

  Once you start creating your INSERT SQL statement with this command, you should proceed to complete construction of the command and perform it without calling subroutines or doing any other unrelated commands. Other commands may cause side effects in the storage used to create your SQL statement.

  QUALIFIER	An optional qualifier in case the table is associated with a user ID other than that logged on to the database at this workstation. Leave this off if the tables are owned by the current user ID.
  TABLE_NAME	The name of the table within the database.

  Examples:
   
    // Use the qualifier and table directly
    Insert_DB_Table( PERSONNEL.EMPLOYEES )
  
    // Use a variable for the parameter
    Set ( UV1, "PERSONNEL.EMPLOYEES" )
    Insert_DB_Table ( UV1 )
  
  

  Label

    Label:
  

  Any text at the beginning of a line in the command file that is ended with a colon will be compiled as a label to which control can be transferred with Goto or any other label reference in other commands. The label can be up to 31 characters long, not including the colon, and is not case sensitive.

  There may be up to 256 labels in a command file, and up to 1800 total references to those labels. References are made by Goto and Call_Subroutine commands and any other commands that include an error label in their parameters.

  Example:
   
    SQL_Error_Label:
  

  LDAP_AdminBind

    LDAP_AdminBind ( LDAP_Connection_Handle_UV, LDAP_Server*, Port*, LDAP_Version*, 
                         Admin_User_dn*, Admin_Encrypted_PW*, Blowfish_Key*, Error_label )
  

  Establishes an administrator connection to an LDAP server. This command would typically be called from a StartLogon script in a TC session that primarily or exclusively handles LDAP transactions.

  The LAST_ERROR data part will be set to the error code returned by LDAP; 0 indicates success. If an error occurred, additional information will be written to the error and trace logs. Some specific errors that might be encountered with this command include:

  • -1 = (TC generated) Memory allocation error.
  • 49 = (LDAP_INVALID_CREDENTIALS) The Admin User dn and password combination was not valid.
  • 81 = (LDAP_SERVER_DOWN) Could not communicate with the specified LDAP server.
  • 90 = (LDAP_NO_MEMORY) Failed to allocate memory to store server/port/version information that is associated with the connection.

  All parameters, except for the connection user variable and error label, can be specified as a quoted string, a user variable, or a data part.

  LDAP_Connection_Handle_UV	This is the user variable in which the command will store the connection handle. A global user variable should be reserved for the LDAP connection handle that is returned. This handle is used in all of the other TC LDAP commands. Simultaneous connections to multiple servers can be established - as long as different user variables are used for each connection handle.
  LDAP_Server*	This is the IP address or hostname of the LDAP server.
  Port*	This is the LDAP communications port number on the LDAP server. Typically port 389 is for non-SSL communications with the LDAP server while port 636 is for secure SSL communications.
  LDAP_Version*	This is the LDAP version that is in use on the LDAP server. Typically this will be version 3.
  Admin_User_dn*	This is the fully qualified "distinguished name" of the Administrative user for which the connection will be created. An example dn format could be: uid=ABC123,c=us,ou=employees,o=company.com
  Admin_Encrypted_PW*	This is the blowfish encrypted password - which will be a string of hex digits.
  Blowfish_Key*	This is the blowfish key to use to decrypt the password - which of course must match the key used to encrypt the password. Note that the key provided here is only part of the actual key used in the decrypt/encrypt processes. Both TC and the DCConnect Client (ENCRYPT command) use a fixed private key which is combined with the script-provided key to create the full key that is used in the decrypt and encrypt processes.
  Error_label	The error label to branch to if an LDAP error occurs - such as the password being invalid for the specified dn. If the label is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends.

  Example:
    LDAP_AdminBind ( gLDAPConnection,"employee.dir.company.com", 389, 3, 
                     "uid=-055VN897,c=us,ou=employee.dir,o=company.com", uvEncryptedPW, uvBlowfishKey, ldap_failed_label )
  

  LDAP_AdminUnbind

    LDAP_AdminUnbind ( LDAP_Connection_Handle_UV, Error_label )
  

  Disconnects the administrator connection to an LDAP server. This command would typically be called from a StartLogoff script in a TC session that primarily or exclusively handles LDAP transactions.

  The LAST_ERROR data part will be set to the error code returned by LDAP; 0 indicates success. If an error occurred, additional information will be written to the error and trace logs. Some specific errors that might be encountered with this command include:

  • 21 = (LDAP_INVALID_SYNTAX) The provided connection handle was null.
  • 89 = (LDAP_PARAM_ERROR) One possibility is that the connection handle passed in was not found in the cache of valid connection handles.

  LDAP_Connection_Handle_UV	This is the user variable which contains the connection handle that was originally obtained from a call to LDAP_AdminBind.
  Error_label	The error label to branch to if an LDAP error occurs - such as the connection handle being invalid. If the label is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends.

  Example:
   
    LDAP_AdminUnbind ( gLDAPConnection, ldap_failed_label )
  
  

  LDAP_Encrypt

    LDAP_Encrypt( UV_For_Encrypted_String, String_To_Encrypt, Blowfish_key )
  

  Use this command to encrypt a string of text using the blowfish encryption algorithm.

  UV_For_Encrypted_String	This is the user variable into which TC will put the encrypted string.
  String_To_Encrypt	This is a string enclosed in double quotes or a user variable or a data part for the string that should be encrypted.
  Blowfish_key	This is the blowfish key to use to encrypt the string. Note that the key provided here is only part of the actual key used in the decrypt/encrypt processes. Both TC and the DCConnect Client (ENCRYPT command) use a fixed private key which is combined with the script-provided key to create the full key that is used in the decrypt and encrypt processes.

  Example:
   
    LDAP_Encrypt ( uvEncryptedPW, uvPwToEncrypt, uvBlowfishKey )
  
  

  LDAP_ChangePassword

    LDAP_ChangePassword ( LDAP_Connection_Handle_UV, Base_dn*, Search_Scope*,
                            UserID_Search_Criteria*, Encrypted_Old_PW*, Encrypted_New_PW*, Blowfish_Key*, 
                            PW_Attribute_Name*, Error_label )
  

  Provides the ability to change a users's password in an LDAP directory server. There are two mechanisms by which this can be done:

  1. Using the LDAP administrator user ID a user's password can be changed without knowing the current password for that user. However, the directory must be configured to allow this option and the adminstrator user ID (used in LDAP_AdminBind) must have the permission to perform this action. To use this mechanism, pass a zero-length string for the Encrypted_Old_PW.
  2. Using the specified user's user ID replace the old password with the new password. If the old password that is provided is not currently valid, the password change cannot be performed. This mechanism is used if the Encrypted_Old_PW is not zero-length.

  As is the case for the LDAP_ValidateUser command, since LDAP actually requires a full distinguished name (dn) along with the password when these credentials are validated and/or the password is changed, users will typically enter something simpler such as a numeric badge ID or an email address rather than the full dn. Therefore LDAP_ChangePassword must look up the full dn based on the user-provided user ID. The LDAP attribute that applies to the user ID value might vary (e.g. 'cn', 'email', 'uid', 'uniquemember'); therefore LDAP_ChangePassword needs to be told which one should be used. This is accomplished via the UserID_Search_Criteria parameter. The TC script should take the user-provided user ID value and build it into a search criteria string that LDAP_ChangePassword will use to lookup the dn value from the LDAP server. An example search criteria string for the user-provided user ID 123456897 could be:

  	(&(uid=123456897))
  

  Note that a single Blowfish_Key parameter applies to both password parameters (unless the Encrypted_Old_PW is blank).

  Note also that in order to be able to change the password, there must be a SSL connection established with the LDAP server. Therefore in the LDAP_AdminBind command, the port parameter should specify an SSL port (typically port 636).

  The LAST_ERROR data part will be set to the error code returned by LDAP; 0 indicates success. If an error occurred, additional information will be written to the error and trace logs. Some specific errors that might be encountered with this command include:

  • -1 = (TC generated) Memory allocation error.
  • -2 = (TC generated) Invalid search scope parameter
  • 21 = (LDAP_INVALID_SYNTAX) The provided connection handle was null.
  • 49 = (LDAP_INVALID_CREDENTIALS) The User dn and password combination was not valid.
  • 50 = (LDAP_INSUFFICIENT_RIGHTS) If no old password was specified, this indicates the admin user does not have the permissions to change the password. If an old password is provided, then the user does not have permission to change their own password.
  • 53 = (LDAP_UNWILLING_TO_PERFORM) This may indicate that the password change was not allowed because an SSL connection to the LDAP server was not being used.
  • 89 = (LDAP_PARAM_ERROR) One possibility is that the connection handle passed in was not found in the cache of valid connection handles.

  All parameters, except for the connection user variable and error label, can be specified as a quoted string, a user variable, or a data part.

  LDAP_Connection_Handle_UV	This is the user variable which contains the connection handle that was originally obtained from a call to LDAP_AdminBind.
  Base_dn*	This is the root entry in the LDAP directory tree from which the dn search should be performed. A sample base dn might look like: ou=employeedir,o=company.com.
  Search_Scope*	Indicates how much of the directory tree should be searched for the dn correlating to the user ID, relative to the base dn. This can be one of the following keywords (without double quotes): LDAP_SCOPE_BASE = Search only the base entry. LDAP_SCOPE_ONELEVEL = Search all entries in the first level below the base entry, excluding the base entry. LDAP_SCOPE_SUBTREE = Search the base entry and all entries in the tree below the base. Alternatively you can specify a user variable or data part that will contain one of the above 3 values at execution time.
  UserID_Search_Criteria*	This specifies the criteria to use to look up the dn for a particular user-provided user ID. See the discussion above for more information about the user ID vs the dn. The search criteria must be specified in the LDAP notation, such as: (&(mail=employeename@us.ibm.com)). This is also known as "Search Filter Syntax". As of June 2013, the following Microsoft website described search filter syntax.
  Encrypted_Old_PW*	This is the blowfish encrypted old password - which will be a string of hex digits. If this is a zero-length string, then TC will use the admin user ID to attempt the password change for the specified user.
  Encrypted_New_PW*	This is the blowfish encrypted new password - which will be a string of hex digits.
  Blowfish_Key*	This is the blowfish key to use to decrypt the password(s) - which of course must match the key used to encrypt the password(s). Note that the key provided here is only part of the actual key used in the decrypt/encrypt processes. Both TC and the DCConnect Client (ENCRYPT command) use a fixed private key which is combined with the script-provided key to create the full key that is used in the decrypt and encrypt processes.
  PW_Attribute_Name*	This is the name of the password attribute in the user directory entry. The typical password attribute name is unicodePwd.
  Error_label	The error label to branch to if an LDAP error occurs - such as the password being invalid. If the label is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends.

  Examples:
  
    Change the password using the user's old password:
   
      LDAP_ChangePassword ( gLDAPConnection, "o=ibm.com", LDAP_SCOPE_SUBTREE, "(&(uid=123456897))", uvEncryptedOldPW, uvEncryptedNewPW, uvBlowfishKey, "unicodePwd", LDAP_failed_label )
  
    Change the password using the admin account - by passing a zero-length old password:
  
      LDAP_ChangePassword ( gLDAPConnection, "o=ibm.com", LDAP_SCOPE_SUBTREE, "(&(uid=123456897))", "",               uvEncryptedNewPW, uvBlowfishKey, "unicodePwd", LDAP_failed_label )
  
  

  LDAP_Search

    LDAP_Search ( LDAP_Connection_Handle_UV, Base_dn*, Search_Scope*, Search_Criteria*, 
                      Attribute_List*, Result_XML_Handle_UV, Error_label )
  

  Perform a search against the LDAP server. Given a base dn, the search scope, search criteria and list of one or more attributes to retrieve, the LDAP server is queried and the resulting matching entries are returned in an XML structure that can be navigated using the TC commands XML_EnterElement, XML_GetField2 and XML_LeaveElement.

  The Result_XML_Handle_UV will only be set to a valid XML handle in the case that the LAST_ERROR data part is set to 0, indicating success. It is the responsibility of the script to clean up the returned XML handle using XML_Cleanup once the script has finished processing the results.

  The result set can contain one more matching ENTRYs each containing one or more ATTRIBUTEs, with each attribute containing one or more VALUEs. Note that the 'dn' for each entry is a special kind of attribute that will always be specified in the result set and therefore need not and should not be included in the attribute list. Here is a sample XML result set containing a single ENTRY with its two attributes 'objectclass' and 'notesemail':

  	<ENTRYLIST>
  		<ENTRY>
  			<DN>uid=123456897,c=us,ou=employedir,o=ibm.com</DN>
  			<ATTRIBUTE name="objectclass">
  				<VALUE>person</VALUE>
  				<VALUE>organizationalPerson</VALUE>
  				<VALUE>ibmPerson</VALUE>
  				<VALUE>ePerson</VALUE>
  				<VALUE>top</VALUE>
  			</ATTRIBUTE>
  			<ATTRIBUTE name="notesemail">
  				<VALUE>CN=John Doe/OU=Charlotte/O=IBM@IBMUS</VALUE>
  			</ATTRIBUTE>
  		</ENTRY>
  	</ENTRYLIST>
  

  As the example above illustrates, the top level element is the ENTRYLIST, which will contain one or more ENTRY elements. Use XML_EnterElement with a different 'occurrence' number to access each ENTRY element. The DN element of an ENTRY element uniquely identifies it from the other ENTRY elements. Each ATTRIBUTE element within an ENTRY element has a 'name' attribute value that should be used in XML_EnterElement to locate the correct ATTRIBUTE when more than one are returned. Finally, the XML_GetField2 command should be used with a different 'occurrence' number to access each VALUE element that might be contained in the ATTRIBUTE element.

  The attribute list can include not only attributes from the specified directory entry but it can also include one of the predefined TC 'attribute functions' for specific attribute values. The syntax of an attribute function is:

    function_name(attribute_name)
  

  Note: Spaces are allowed around the opening and closing parentheses; but they will be stripped out when the attribute list is processed. So when the <ATTRIBUTE> element is added to the response XML structure for the attribute function, the spaces will be removed. Therefore when using XML_EnterElement to enter the <ATTRIBUTE> element be sure not to include any spaces. The second example below illustrates this.

  In the case that an attribute function is specified, the result of the function will be returned not the attribute value itself. But the attribute list can include both the attribute name by itself and the attribute function that acts on that attribute. The predefined list of attribute functions is:

  • LDAP_PW_AGE_IN_DAYS(pwdLastSet) calculates the age of the password in days from the pwdLastSet attribute which is a date value indicating on which day the password was last changed. If the attribute name in the directory is something other than pwdLastSet, that other name should be used.

  The following is an example XML response that includes the pwdLastSet value and the value for the function LDAP_PW_AGE_IN_DAYS(pwdLastSet):

  	<ENTRYLIST>
  		<ENTRY>
  			<DN>uid=123456897,c=us,ou=employedir,o=ibm.com</DN>
  			<ATTRIBUTE name="pwdLastSet">
  				<VALUE>130255074216183596</VALUE>
  			</ATTRIBUTE>
  			<ATTRIBUTE name="LDAP_PW_AGE_IN_DAYS(pwdLastSet)">
  				<VALUE>23</VALUE>
  			</ATTRIBUTE>
  		</ENTRY>
  	</ENTRYLIST>
  

  The LAST_ERROR data part will be set to the error code returned by LDAP; 0 indicates success. If an error occurred, additional information will be written to the error and trace logs. Some specific errors that might be encountered with this command include:

  • -1 = (TC generated) Memory allocation error
  • -2 = (TC generated) Invalid search scope parameter
  • 21 = (LDAP_INVALID_SYNTAX) The provided connection handle was null.
  • 89 = (LDAP_PARAM_ERROR) One possibility is that the connection handle passed in was not found in the cache of valid connection handles.
  • 94 = (LDAP_NO_RESULTS_RETURNED) Nothing was found that matched the specified search criteria and scope.

  All parameters, except the connection user variable, result user variable and error label, can be specified as a quoted string, a user variable, or a data part.

  LDAP_Connection_Handle_UV	This is the user variable which contains the connection handle that was originally obtained from a call to LDAP_AdminBind.
  Base_dn*	This is the root entry in the LDAP directory tree from which the search should be performed. A sample base dn might look like: ou=employeedir,o=company.com.
  Search_Scope*	Indicates how much of the directory tree should be searched, relative to the base dn. This can be one of the following keywords (without double quotes): LDAP_SCOPE_BASE = Search only the base entry. LDAP_SCOPE_ONELEVEL = Search all entries in the first level below the base entry, excluding the base entry. LDAP_SCOPE_SUBTREE = Search the base entry and all entries in the tree below the base. Alternatively you can specify a user variable or data part that will contain one of the above 3 values at execution time.
  Search_Criteria*	This specifies the criteria to match among the entries that are in the search scope. The search criteria must be specified in the LDAP notation, such as: (&(mail=employeename@us.ibm.com)). This is also known as "Search Filter Syntax". As of June 2013, the following Microsoft website described search filter syntax.
  Attribute_List*	List of one or more comma-separated attribute names to be retrieved from each entry that matches the specfied search parameters. Note that 'dn' is a special kind of attribute for each entry which will always be returned in the response XML as is illustrated above; you need not and should not include it in the attribute list. See the discussion above about the use of attribute functions.
  Result_XML_Handle_UV	The user variable in which TC should put the XML handle for the result set that is returned. This will only be valid if the LAST_ERROR value is 0 after the command completes. Be sure to clean up the handle when done processing the result set.
  Error_label	The error label to branch to if an LDAP error occurs - such as the Search Scope parameter being invalid. If the label is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends.

  Examples:
   
    The following call resulted in the returned XML shown above:
  
      Declare ( searchResultsXML )
  
      LDAP_Search (gLDAPConnection, "ou=employeedir,o=ibm.com", LDAP_SCOPE_SUBTREE, "(&(mail=jdoe@us.ibm.com))",
                   "objectclass, notesemail", searchResultsXML, ldap_search_failed_label )
  
    Use the LDAP_PW_AGE_IN_DAYS attribute function on the pwdLastSet attribute to retrieve the password age for the same user as the 
    previous example:
  
      Declare ( pwAge )
      Declare ( userValuesDocHandle )
      ...
  
      LDAP_Search ( gLDAPConnection, "ou=employeedir,o=ibm.com", LDAP_SCOPE_SUBTREE, "(&(mail=jdoe@us.ibm.com))",  "LDAP_PW_AGE_IN_DAYS ( pwdLastSet )", userValuesDocHandle, LDAP_failed_label ) 
  
      XML_EnterElement(userValuesDocHandle, "ENTRY", PwdAgeNotFound)
  
          XML_EnterElement(userValuesDocHandle, "ATTRIBUTE", "name", "LDAP_PW_AGE_IN_DAYS(pwdLastSet)", "1", PwdAgeNotFound)
  
              XML_GetField2(userValuesDocHandle, "VALUE", 1, pwAge, PwdAgeNotFound)
  
              goto (DonePWAge)
  
    PwdAgeNotFound:
  
      // If not found, default age to 0. 
      Log_Error ("Failed to get password age from directory")
      UV_Math (pwAge, =, 0.0)
  
    DonePwAge:
      XML_Cleanup( userValuesDocHandle )  
  
    LDAP_failed_Label:
  
  
  

  LDAP_ValidateUser

    LDAP_ValidateUser ( LDAP_Connection_Handle_UV, Base_dn*, Search_Scope*,
                            UserID_Search_Criteria*, Encrypted_PW*, Blowfish_Key*, 
                            [*attributeList, resultXMLHandle,] Error_label )
  

  Given a user ID and blowfish encrypted password, send the credentials to the LDAP server for validation. Note that LDAP actually requires a full distinguished name (dn) along with the password when these credentials are validated. However, users typically enter something simpler such as a numeric badge ID or an email address rather than the full dn. Therefore LDAP_ValidateUser must look up the full dn based on the user-provided user ID. The LDAP attribute that applies to the user ID value might vary (e.g. 'cn', 'email', 'uid', 'uniquemember'); therefore LDAP_ValidateUser; needs to be told which one should be used. This is accomplished via the UserID_Search_Criteria parameter. The TC script should take the user-provided user ID value and build it into a search criteria string that LDAP_ValidateUser will use to lookup the dn value from the LDAP server. An example search criteria string for the user-provided user ID 123456897 could be:

  	(&(uid=123456897))
  

  Optionally this call can be used to extract attribute values from the specified user's directory entry; but this is only done if the credentials provide are successfully validated. The attributeList and resultXMLHandle parameters should only be include if attributes are to be retrieved. One example might be the attribute for the date that the password was last changed (pwdLastSet). There is also a special attribute function that can be used to perform an operation on the retrieved attribute. If attributes are retrieved they are returned in the same XML format that LDAP_Search returns attribute values. See LDAP_Search for information about the attribute functions and the response XML format.

  The LAST_ERROR data part will be set to the error code returned by LDAP; 0 indicates success. If an error occurred, additional information will be written to the error and trace logs. Some specific errors that might be encountered with this command include:

  • -1 = (TC generated) Memory allocation error.
  • -2 = (TC generated) Invalid search scope parameter
  • 21 = (LDAP_INVALID_SYNTAX) The provided connection handle was null.
  • 49 = (LDAP_INVALID_CREDENTIALS) The User dn and password combination was not valid.
  • 89 = (LDAP_PARAM_ERROR) One possibility is that the connection handle passed in was not found in the cache of valid connection handles.
  • 94 = (LDAP_NO_RESULTS_RETURNED) Nothing was found that matched the specified search criteria and scope. Applies only when an attributeList is provided.

  All parameters, except for the connection user variable, result user variable and error label, can be specified as a quoted string, a user variable, or a data part.

  LDAP_Connection_Handle_UV	This is the user variable which contains the connection handle that was originally obtained from a call to LDAP_AdminBind.
  Base_dn*	This is the root entry in the LDAP directory tree from which the dn search should be performed. A sample base dn might look like: ou=employeedir,o=company.com.
  Search_Scope*	Indicates how much of the directory tree should be searched for the dn correlating to the user ID, relative to the base dn. This can be one of the following keywords (without double quotes): LDAP_SCOPE_BASE = Search only the base entry. LDAP_SCOPE_ONELEVEL = Search all entries in the first level below the base entry, excluding the base entry. LDAP_SCOPE_SUBTREE = Search the base entry and all entries in the tree below the base. Alternatively you can specify a user variable or data part that will contain one of the above 3 values at execution time.
  UserID_Search_Criteria*	This specifies the criteria to use to look up the dn for a particular user-provided user ID. See the discussion above for more information about the user ID vs the dn. The search criteria must be specified in the LDAP notation, such as: (&(mail=employeename@us.ibm.com)). This is also known as "Search Filter Syntax". As of June 2013, the following Microsoft website described search filter syntax.
  Encrypted_PW*	This is the blowfish encrypted password - which will be a string of hex digits.
  Blowfish_Key*	This is the blowfish key to use to decrypt the password - which of course must match the key used to encrypt the password. Note that the key provided here is only part of the actual key used in the decrypt/encrypt processes. Both TC and the DCConnect Client (ENCRYPT command) use a fixed private key which is combined with the script-provided key to create the full key that is used in the decrypt and encrypt processes.
  Attribute_List*	Optional list of one or more comma-separated attribute names to be retrieved from the directory entry for the specfied user. Please see LDAP_Search for information about the attribute list format, attribute functions and the format of the XML response. If this optional parameter is used, the Result_XML_Handle_UV parameter must also be provided in order to receive the XML response containing the attribute values.
  Result_XML_Handle_UV	The user variable in which TC should put the XML handle for the result set that is returned. This will only be valid if the LAST_ERROR value is 0 after the command completes. Be sure to cleanup the handle when done processing the result set. This parameter should be included if and only if the Attribute_List parameter is also provided.
  Error_label	The error label to branch to if an LDAP error occurs - such as the password being invalid. If the label is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends.

  Examples:
  
    Validate user without retrieving any attributes:
   
      LDAP_ValidateUser ( gLDAPConnection, "o=ibm.com", LDAP_SCOPE_SUBTREE, "(&(uid=123456897))", uvEncryptedPW, uvBlowfishKey, LDAP_failed_label )
  
    Validate user and retrieve the password age:
  
      Declare ( pwAge )
      Declare ( userValuesDocHandle )
      ...
  
      LDAP_ValidateUser ( gLDAPConnection, "o=ibm.com", LDAP_SCOPE_SUBTREE, "(&(uid=123456897))", uvEncryptedPW, uvBlowfishKey, "LDAP_PW_AGE_IN_DAYS ( pwdLastSet )", userValuesDocHandle, LDAP_failed_label ) 
  
      XML_EnterElement(userValuesDocHandle, "ENTRY", PwdAgeNotFound)
  
          XML_EnterElement(userValuesDocHandle, "ATTRIBUTE", "name", "LDAP_PW_AGE_IN_DAYS(pwdLastSet)", "1", PwdAgeNotFound)
  
              XML_GetField2(userValuesDocHandle, "VALUE", 1, pwAge, PwdAgeNotFound)
  
              goto (DonePWAge)
  
    PwdAgeNotFound:
  
      // If not found, default age to 0. 
      Log_Error ("Failed to get password age from directory")
      UV_Math (pwAge, =, 0.0)
  
    DonePwAge:
      XML_Cleanup( userValuesDocHandle )  
  
    LDAP_failed_Label:
  
  

  Load_Term / Load_Terminal

    Load_Term ( TERMNAME_UV, WHICH_FILES, RETURN_WHEN )
    Load_Term ( TERMNAME_UV, WHICH_FILES, RETURN_WHEN , ERR_LABEL )
  

  Starts a full or partial download of the specified terminal.

  TERMNAME_UV	User variable containing the name of the terminal which is to be downloaded.
  WHICH_FILES	Specifies which set of files should be loaded to the terminal. Choose one of the following keywords: ETS ALL CFR VAL GRAPHICS RESET SCRIPTS CLIENT
  RETURN_WHEN	Specifies whether or not TC should wait for the entire download process to complete before the next command is executed or whether TC should simply notified when the download is started or is queued. Choose one of the following keywords: WHEN_COMPLETE WHEN_STARTED WHEN_QUEUED
  ERR_LABEL	An optional label to branch to when TC encounters an error when trying to download the DCT. For example, an RF terminal may have moved out of range or may have been turned off by the operator. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends.

  Examples:
   
    // Start a complete download on terminal BackDock23; return when request is queued
    Set_UV_Kbd_Data (uvTerminalName, "BackDock23");
    Load_Term(uvTerminalName, ALL, WHEN_QUEUED, FailedToStart)
  

  Load_UVs

    Load_UVs()
  

  This command loads from disk storage the contents of user variables UV1 through UV20 for the current terminal, restoring the user variables to their state when the command Save_UVs was last used for the current terminal. This allows for a continuity of data processing for individual terminals, even though this session of TC may be handling similar interspersed transactions from multiple terminals in succession.

  For example, because the 7526 and 7527 terminal can send a maximum transaction size of only 104 characters, you may need to be able to combine 2 or more transactions from a terminal into one larger transaction to the database. When your script recognizes the first transaction of the series coming in (based on its key ID or a matching data identifier; see Startkey and StartMatch commands), it can save this first part of the overall data in one of user variables (only UV1 through UV20 are valid for this purpose). Then when the second (and any further) parts of the overall data come in succeeding transactions, the earlier parts can be loaded from disk and combined with the new data for further processing.

  The user variable data is saved in files that are uniquely named based on the terminal's physical address and the session's controller ID. A physical terminal can have more than 1 file containing user variable data on your personal computer if that terminal sends transactions to more than 1 session. However, for a particular session, there is only 1 file for a particular physical terminal. All transactions handled from that terminal must be processed in the scripts to cooperatively use the 20 user variables that can be saved and re-loaded.

  Note: Due to the way terminal addresses are reported by DCConnect and the way the file extension is derived, the file extension for RF terminal addresses 100-126 are the same as for RF terminals 0-26. It is recommended that you do not use this function for RF terminals with addresses in both ranges at the same time. In Data Request mode, if the ORIGINATOR of the Data Request is an application instead of a terminal, the first three characters of the ORIGINATOR name are used for the extension.

  User variables UV21 and up are not stored or retrieved with the Save_UVs / Load_UVs commands. These user variables are always shared between all terminals and all transactions processed through the TC session. This allows for the possibility of inter-terminal communication using these shared memory areas.

  If a Load_UVs command is executed prior to any Save_UVs command (that is, there is no file from which to load), UV1 through UV20 are not changed.

  Example:
   
    // Part A of a big transaction comes in with the
    // identifier 'PTA' as the first 3 characters of data
    StartMatch ( "PTA", TXNDATA, 0, 3 )
   
      // Clear UV1 and append it to 98 characters
      // of the transaction that follow the PTA identifier,
      // then save UV1-UV20 and release the transaction.
      Clear_UV( UV1 )
      Append_UV_Xact_Data( UV1, TXNDATA, 3, 98 )
      Save_UVs()
      Release_Xact()
   
    EndMatch()
   
    // Part B of a big transaction comes in with the
    // identifier 'PTB' as the first 3 characters of data.
    // This is the final part of the transaction.
    StartMatch ( "PTB", TXNDATA, 0, 3 )
   
      // Load the stored user variables for this
      // terminal.  This will bring in the Part A
      // data that was stored from the first transaction
      Load_UVs()
   
      // We have an error if, for some reason, we received
      // part B but have no part A.  If part A, stored in UV1,
      // is missing (that is, UV1 is empty), goto error recovery.
      // Use a cleared UV30 as a test against UV1:
      Clear_UV( UV30 )
      If ( UV1 == UV30)
        Goto PART_A_MISSING
   
      // Clear UV2 and append it to 70 characters
      // of the transaction that follow the PTB identifier,
      // then proceed to do remaining processing.
      Clear_UV( UV2 )
      Append_UV_Xact_Data( UV2, TXNDATA, 3, 70 )
      Release_Xact()
   
      // Do other processing with the data in UV1 and UV2....
   
    EndMatch()
  

  Log_Data

    Log_Data( FILENAME,     UV, MODE, RC_UV )
    Log_Data( FILENAME.EXT, UV, MODE, RC_UV )
    Log_Data( FILE_UV,      UV, MODE, RC_UV )
  

  This command logs the current data from a TC user variable to the data file specified. This can be used to create a file containing a report generated from a query. The report file can then be sent to the terminal for viewing or printing, or it can be used by some other process. It can be used create logs of activity from all terminals using the session's processing or logs for each individual terminal, as well as files to route to printers accessible to the PC.

  If the filename specified by the first parameter does not include a backslash (\) in the name, TC assumes the file is to be created in the directory defined by the TC2 environment variable. So to specify the current directory on the current drive, use .\ before the file name. To specify the current directory on a different drive, use d:.\ in front of the name, where d: is the other drive letter.

  TC automatically retries 10 times at 250 millisecond intervals to open and write to the file to handle cases where another application (even another TC session) may also be using the file. See the description of RC_UV below for details of what happens if the file access cannot be accomplished.

  FILENAME, FILENAME.EXT, or FILE_UV	The file name for the data file. This can include path information and can be either a constant string value or the current value of a user variable. If no extension (.EXT) is given TC creates an extension representing the physical address of the data collection terminal whose transaction/validation request is being processed. This extension consists of the location number (0-3, ' ', F, P, W), the location's line (0-7), and the terminal address character (A-Y, 0-6, or 0-9). For example, if you specify REPORT as the FILENAME and the transaction came from the terminal connected to ARTIC card 0, line 6, with address B, the file name is assigned as REPORT.06B. Note: To avoid having a 7527 and a 7526/7525 terminal on an ARTIC line receive the same automatically generated file extension, you must not have a 7527 with address 'A' and a 7526/7525 with address 'a'. The operating system does not often distinguish the case of letters in a file name. 7524 RF terminals are connected through an RF serial line, and use 3-digit numeric addresses instead of a single character. DCConnect reports the 7524 terminal's address as "RFxyz", where xyz is the 3-digit number. TC uses the 'F' and the 'yz' digits to create the file extension automatically; you are limited to using terminals 001 to 099 to avoid having two terminals receive the same file extension on their report files. TCP/IP 75xx attached terminals report their addresses as "IPxya". TC generates the extension "Pya" from this. This is unique for all possible TCP/IP terminals. DWTS terminals report an address of "DWxya". TC generates the extension "Wya" from this. This is unique for all possible DOS and Windows terminals. Serial attached terminals specify a space for the location characters. This results in a unique and valid extension. In Data Request mode, if the originator of the data request is an application instead of a terminal, the first three characters of the originator name are used for the extension. If the FILENAME begins with the letters 'LPT' and no extension is given, TC assumes you mean to use a line printer for the output, and no automatic file extension is made. If the filename parameter is a literal string, it may contain one or more environment variables which are denoted by their starting and ending percent signs (%). TC will resolve these environment variables at compile time. If the filename parameter specifies a user variable instead, and at execution time, the data in the user variable contains one or more environment variables, then TC will resolve them before trying to use the data as a file name.
  UV	The TC user variable; not to be confused with the user variables resident in the data collection terminals.
  MODE	The file write mode. Use OVERWRITE to over write any existing data in the file or create a new file if required. Use APPEND to add on to existing data in the file or create a new file if there was no existing file.
  RC_UV	This is the optional return code user variable. If this is not specified, TC will terminate if it encounters any file I/O error (such as trying to write to a file which another application has locked). If this return code variable is specified TC will never terminate due to a file I/O error and it will set the return code to either OK or FAIL.

  Example:
   
      Name_UV( UV50, uvRC )             // For return codes
   
      // Use an empty user variable to start fresh with the file.
      Clear_UV( UV1 )
      Log_Data( REPORT, UV1, OVERWRITE, uvRC )
   
    // Loop through, adding data to the file
    // from a previous SELECT statement.
    Fetch_more:
   
      Perform_Fetch(No_more_data_27);
   
      Clear_UV(UV1)
      Clear_UV(UV2)
   
      Append_UV_Kbd_Data( UV1, "BADGE = ")
      Append_UV_Select_Data( UV1, 2, SQLerror, 7 )
      Append_UV_Kbd_Data( UV1, " ; COUNT OF RECORDS = ")
      Append_UV_Select_Data( UV1, 1, SQLerror, 7)
   
      // Add carriage return and line feed
      Append_UV_Kbd_Data( UV1, CRLF)
   
      Log_Data ( REPORT, UV1, APPEND, uvRC )
   
   
      Send_Term_UV_Data( UV1, 10 )
   
      Goto( Fetch_more )
  

  Log_Error

    Log_Error( message )
    Log_Error( message, TYPE )
    Log_Error( UV )
    Log_Error( UV, TYPE )
  

  This command logs your individualized error message to the TC2ERRx.LOG error log file (where x is the controller ID for this TC session).

  Message	The message string can be up to 240 characters long.
  TYPE	Up to 5 characters describing the type of message (e.g. INFO, WARN, etc.) Type is optional, with the default being ERROR.
  UV	A UV number or named UV that has the content of the message to be displayed.

  Example:
   
    Log_Error( "Some kind of error message" )
  

  Log_Xact

    Log_Xact( file_name )
  

  This command logs the current transaction to the file name of your choice.

  TC will take the file_name provided and will append to the front of it, the directory defined by the TC2 environment variable. Therefore, do not include a path as part of the file_name parameter.

  The filename parameter may contain one or more environment variables which are denoted by their starting and ending percent signs (%). TC will resolve these environment variables at compile time. However, the environment variable(s) should specify only a file name and not any path.

  This command is not applicable when the session is operating in remote validation or data request mode. (**) (66)

  Example:
   
    Log_Xact( XACTLOG.DAT )
  

  Mailbox / Export

    Mailbox ( NAME | REMOTE_VALIDATION | DATA_REQUEST)
    Export ( NAME | REMOTE_VALIDATION | DATA_REQUEST)
  

  This function is used to name the DCConnect Mailbox (formerly called export) from which a TC session reads transactions.

  If your TC session is processing validation requests instead of transactions, then you should specify the keyword:

    REMOTE_VALIDATION
  

  instead of an actual mailbox name. In this case, the TC session determines which validation files should be handled from all of the StartVal commands that are encountered in the script. The Application function can be used to override the default application name that the TC session would otherwise use when registering with DCConnect to receive validation requests. The default application name is based on the controller ID.

  If your TC session is processing data requests instead of transactions or validation requests, then you should specify the keyword:

    DATA_REQUEST
  

  instead of an actual mailbox name. In this case, you must use the Application function to specify the application name. The TC session uses that application name when registering itself with DCConnect to handle data requests.

  Refer to Transaction, Remote Validation, or Data Request Modes for additional information.

  If you want to run a TC session that does not handle transactions, validation requests or data requests, do not include the Mailbox() command in the script and do not specify it on the command line. This can be useful if your TC session is only going to be performing a simple operation on an interval basis - such as downloading files from an AS/400 twice a day.

  NAME

  The up-to-32 character name of the DCConnect mailbox. The name must match the DCConnect mailbox name exactly, including capitalization. As described above, the keywords REMOTE_VALIDATION or DATA_REQUEST can be used in place of the mailbox name. The name may be enclosed in double quotes. If it is, the double quotes are removed before the name is stored.

  Example:
   
    // Specify that TC should read transactions from the mailbox 'STOCK_ROOM'
    Mailbox ( STOCK_ROOM )
   
  

  Make_Data_Request

    Make_Data_Request ( RECEIVER_NAME, SENDER_NAME, REQUEST_UV,
                              REPLY_UV, TIME_LIMIT*)
    Make_Data_Request ( RECEIVER_NAME, SENDER_NAME, REQUEST_UV,
                              REPLY_UV, TIME_LIMIT*, ERROR_LABEL)
  

  This function allows the TC session to make a request of another application that is servicing data requests. The request is actually routed through DCConnect which makes sure it gets to the application specified by the RECEIVER_NAME. That application then processes the request and sends a reply back through DCConnect.

  The TC session does NOT have to be running in DATA_REQUEST mode in order to use this function. Issuing this call can be thought of as acting like a client, whereas running in DATA_REQUEST mode would be acting as a server.

  Note: If running in DATA_REQUEST mode, a particular TC session can make data requests of other TC sessions but it cannot make a request of itself. The Make_Data_Request function does not return until the reply is given or a timeout occurs; therefore there is no way a TC session could process its own request.

  Data requests and their replies are allowed to be up to 16383 characters in length. By default only user variables 241 through 250 are of this size, it is recommended they be the user variables that are used in this function. However, if you know the request and reply data will never exceed 235 bytes, any user variable can be used. In addition, the Define_UVs. command can be used to change the number of large user variables that are available.

  Note: Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a user variable by using the user variable's name or the notation UVn, where n ranges from 1 to 250 or the maximum defined by Define_UVs.

  RECEIVER_NAME	Up-to-32 character name of the application that is supposed to process this request.
  SENDER_NAME	Up-to-32 character name identifying the requester - the TC session making this request. The keyword CURRENT can be used to take the name of the terminal/originator that sent the transaction/request that is currently being processed by the TC session making this request.
  REQUEST_UV	The TC user variable containing the request data; not to be confused with terminal-resident user variables.
  REPLY_UV	The TC user variable in which to store the reply; not to be confused with terminal-resident user variables.
  TIME_LIMIT*	How many seconds to wait for the reply. The range is 0 to 65,535. A limit of 0 means not to wait.
  ERROR_LABEL	The default label to branch to in the event of an error. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control returns to the next command when the subroutine ends. The label is optional; if not specified, the script always executes the next command step.

  Example:
   
    // Send a request to the STOCK_ROOM application and wait
    // up to 10 seconds for the reply.  This is done during
    // processing of a validation request.  So the name of
    // the terminal which made the validation request is used
    // as the 'sender' in the data request.  In effect, the
    // TC session is making a request on behalf of a terminal.
   
    Name_UV( UV241, REQUEST_BUFFER)
    Name_UV( UV242, REPLY_BUFFER)
   
    StartVal ( PALLET.VAL )
   
   
      // ... steps to build request data in REQUEST_BUFFER
   
      Make_Data_Request( STOCK_ROOM, CURRENT, REQUEST_BUFFER,
                         REPLY_BUFFER, 10, Request_Failed)
   
      // ... steps to parse the REPLY_BUFFER and send data to
      // ... the terminal which made the validation request
   
    EndVal
  

  Max_Xact_Wait

    Max_Xact_Wait( TIME )
  

  This command is used to set the maximum time TC waits for a transaction or request to be received from DCConnect before it times out and runs the StartTimeout script (if it has been defined). The StartTimeout script is defined using the commands StartTimeout and EndTimeout.

  This command is useful for tasks such as shutting down TC when no transactions are available for processing.

  This command can be used anywhere in the script command file, and takes effect for all processing done by the TC session.

  TIME	Timeout in units of 1 millisecond (1/1000 seconds) during which TC waits for a transaction/request from DCConnect before executing any timeout script defined by the StartTimeout / EndTimeout command set. The range of milliseconds is 1 to 4,294,967,295 (.001 seconds to 49.7 days).

  Example:
   
    // A manual procedure or a COMMAND file has dialed a modem
    // to connect to headquarters, and a switched line PCOMM
    // remote database connection was started.  As soon as all accumulated
    // DCT transactions have been transferred to the server system,
    // we want to log off and terminate the session, which
    // will allow the phone line to be dropped.
   
    // If no transactions are available for 2 seconds, call
    // the TIMEOUT procedure.  2 seconds is plenty of time
    // for DCConnect to retrieve any available transactions.
    Max_Xact_Wait ( 2000 )
   
    StartTimeout()
   
      Log_Error ( "Transactions completed, logging off...")
   
      End_TC()
   
    EndTimeout()
  

  Multi_Release_Mode

    Multi_Release_Mode()
  

  This command is used to set TC into multiple transaction release mode. By default, TC requires that you release each DCConnect transaction before beginning to process the next one. This mode switch command lets you read as many transactions as you want before releasing them all as a group. You could update tables with multiple transactions from DCTs, while maintaining a copy of each in the DCConnect mailbox until you are ready to commit the changes. If the complete set of transactions cannot be posted to the database at this time, you can use the command Cycle_DCC/2_Export / Cycle_Mailbox to reset the DCConnect mailbox pointers you receive those transactions over again when you want to retry the operation.

  This command can be used anywhere in the script command file, and takes effect for all processing done by the TC session.

  Example:
   
    Multi_Release_Mode
  

  Name_UV

    Name_UV( UVn, ALIAS )
    Name_UV( NEXT_UV, ALIAS )
  

  Give a meaningful alias to a TC user variable. Once the user variable has been given an alias, that alias can be used in other commands. Name_UV commands can be used anywhere in the script, but use of the alias must come after the name is created.

  A user variable may be named only once in a script.

  The NEXT_UV keyword may be used in lieu of a user variable number to indicate that you want to use the next higher number based on the last Name_UV command encountered during compilation of the script. If there have been no prior Name_UV commands then UV1 is the intial user variable used. This method makes it easy to name large blocks of user variables and keep related user variables together in the naming code without need to manually renumber command data when new names are inserted.

  Example:
   
    // Name user variable 30 and 31
    Name_UV( UV30, A_name_for_UV30 )
    Name_UV( NEXT_UV, The_Next_UVs_Name)
  

  No_Display_Execute

    No_Display_Execute
  

  This command allows improved processing speed by turning off the display of each executed step (see Increasing Processing Speed).

  This command can be used anywhere in the script command file, and takes effect for all processing done by the TC session.

  The command Trace, if also included in the script command file, will override the "No_Display_Execute" command.

  Example:
   
    No_Display_Execute
   
    StartKey( F1 )
      ...
  

  No_Terminate_From_DCConnect

    No_Terminate_From_DCConnect
  

  This command is used to tell TC not to terminate when calls to DCConnect APis indicate that the DCConnect Server is shutting down or is not running. It comes into play for any command that maps to a DCConnect API (e.g. Load_Term, Report_Terminal_State, Clear_Mailbox, Sync_Date_Time, ...) as well as internal commands that map to DCConnect APIs such as the thread handles reading transactions / validation requests / data requests from DCConnect. However that thread does terminate TC if 10 attempts in a row fail to read - with a 1 second delay between each.

  This command can be used anywhere in the script command file, and takes effect for all processing done by the TC session.

  Example:
   
    No_Terminate_From_DCConnect
   
    StartKey( F1 )
      ...
  

  On_Error_Goto

    On_Error_Goto( ERROR_CODE, ERROR_LABEL )
  

  This command lets you specify more exactly the actions you want to take when specific SQL errors occur (by native code / SQLSTATE / On Error String) or when a host emulator window SESSION error occurs or when a WEB SERVICE error occurs. You can call the function many times to register as many as 15 different labels to which you want to branch for specific SQL error codes and/or the general emulator session error.

  For SQL-oriented commands, the error codes and corresponding labels you have set up are examined by TC each time that any of the SQL commands that list an error label in their parameters are executed. Your codes and labels are examined first for a match, and if none is found, the error label in the command being executed is used.

  For host emulator window commands, if you specify a LOCKED_OR_BUSY label on the host-oriented command then this label will be used for any locked or busy errors while the label/subroutine specified by the On_Error_Goto command will be used for any other type of EHLLAPI error (e.g. error 1, 2, 7, 9 ). If no label is specified on the command then all errors (including locked/busy) will be routed to the On_Error_Goto label.

  For web service commands, the specified label will be branched to if an error occurs with the command. For those web service commands that have an output return code variable, the branching to the error label occurs when the return code variable is anything but 0. After the branch occurs, that return code variable can be examined. In addition the WS_GetLastErrorText can be called after the branch in order to retrieve any error text. Even for web service commands that do not have a return code parameter, if an internal error occurs and the WEBSERVICE On_Error_Goto command is in effect the branch to the error label will be done.

  You can deactivate the label for a particular error code by calling On_Error_Goto again with the error code of interest, but this time specifying the ERROR_LABEL to be NULL.

  The list of error codes and labels is cleared at the start of each StartKey/StartVal/StartMatch/StartLogon/... script.

  If using IBM DB2, refer to the online Messages References for a complete list of SQLCODE errors and their meaning. SQLxxxxN and SQLxxxxC errors have negative SQLCODE values equal to -xxxx. SQLyyyyW errors have positive SQLCODE values equal to yyyy.

  If using ODBC to connect to the database, consult the database software documentation for a listing of SQLSTATE values and native codes that apply to the database type in use.

  The number of possible errors is quite large, so often it is easier to determine which error values the script should handle by trial and error. To do this, write a simple version of your command file, and then force various types of errors using input from the data collection terminals to see what error codes you get. Then refine your script file to recover from the error gracefully or to advise the terminal operator about how to correct the transaction.

  Prior to fix pack E for the 1.40 version of TC, all error codes specified had to be DB2 native SQLCODE values. With fix pack E came support for ODBC and as a result the DB2 native SQLCODE values were no longer always appropriate. TC was enhanced to support not only existing SQLCODE values in scripts but also to support SQLSTATE values. Support for a third method was also added. This allows the use of 'On Error Strings' which describe the error more clearly in the script. For more information, please see On Error Strings.

  For a complete discussion about the way database errors are handled by TC and how they can be referenced in your scripts, please see How TC Handles SQL Errors.

  ERROR_CODE

  If trying to handle an error with a host emulator session window, use the keyword SESSION. If trying to handle errors for web service commands, use the keyword WEBSERVICE. Otherwise if handling a database error, specify the SQL error code that should be handled. The SQL error code can actually be specified in one of three different ways: A native code value. For example, if DB2 is the type of database to which TC is connected, this is the SQLCODE value that would be returned. Before TC supported ODBC, the native code value was the only option for the first parameter of this command. For example, in order to handle a 'duplicate record' error when connected directly to a DB2 database, the native code value (SQLCODE) of -803 could be specified for this parameter. An SQLSTATE value. This is a more standardized way for different database types to denote a particular error condition. Native codes tend to be unique to each database type. So if your TC script will need to work with more than one database type (e.g. DB2, Oracle, SQL Server, Lotus Notes, ...), you'll need to use SQLSTATE values instead of native code values in your On_Error_Goto commands. For more information about different ways that the SQLSTATE can be specified, please see Specifying SQLSTATE values. An On Error String - this is actually a more descriptive alias for an SQLSTATE value and/or native code value. On Error Strings have to be mapped to native code/SQLSTATE values either using the Define_On_Error_String script command or by adding an entry to the file RC_USER.INI. All entries in RC_DB2.INI and RC_ODBC.INI include mappings to On Error Strings. For more information about On Error Strings and how they are defined, please see On Error Strings.

  ERROR_LABEL

  The default label to branch to in the event of an error. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends.

  Examples:
   
    // If we try to do an Update and no row matches the WHERE conditions,
    // go Insert a row instead.  The DB2 SQLCODE 100 (SQL0100W) is returned
    // in this case.  It also happens to be true that 100 is the native code
    // returned by the ODBC driver for many database types when the operation
    // returns no rows; however this is likely the only native code for which
    // that is TRUE.
    On_Error_Goto( 100, NO_ROW_FOUND)
   
     // Remove the special handling for this SQL error code
    On_Error_Goto ( 100, NULL )
   
   
    // If an attempt at Insert fails due to an existing record with
    // a unique key value already used, go do an Update instead.
    On_Error_Goto ( -803, DO_UPDATE_INSTEAD );
   
     // Now use the SQLSTATE value instead
    On_Error_Goto ( SQL23505, DO_UPDATE_INSTEAD );
   
     // Now use the On Error String for this same error - which is defined in
     // both RC_DB2.INI and RC_ODBC.INI
    On_Error_Goto ( OE DUPLICATE RECORD, DO_UPDATE_INSTEAD );
   
   
     // Trap bad EHLLAPI errors (typically associated with sudden, unexpected
     // loss of the host session due to host being IPLed, LAN problems, etc.)
    On_Error_Goto( SESSION, lblHLLError )
   
    Send_To_Host( ENTER, lblLockedorBusy )
  

  Open_File_Data

    Open_File_Data( uvRC, "filename.ext" )
    Open_File_Data( uvRC, DATAPART, START, LENGTH )
  

  This command is called to open a flat file for reading data into a user variable. The flat file name may be specified literally in the command or it may be contained in a user variable.

  Unlike the Log_Data command, TC will NOT append to the front of the file name provided the directory defined by the TC2 environment variable.

  The file remains open until TC terminates or a Close_File_Data or a new Open_File_Data command is encountered.

  uvRC	The user variable you specify for uvRC shows the return code from the file open. A value of 0 indicate success. Any other value indicate failure: 0 NO_ERROR 5 ERROR_ACCESS_DENIED 6 ERROR_INVALID_HANDLE 26 ERROR_NOT_DOS_DISK 33 ERROR_LOCK_VIOLATION 109 ERROR_BROKEN_PIPE 234 ERROR_MORE_DATA
  filename	A quoted string providing the filename to open. If the filename parameter is a literal string, it may contain one or more environment variables which are denoted by their starting and ending percent signs (%). TC will resolve these environment variables at compile time.
  DATA_PART	This specifies one of various predefined parts of the terminal transaction or other data part that will contain the file name to be opened. The predefined parts for this parameter are shown in Data Parts. The data parts that are valid vary depending on whether the TC session is currently running in transaction, validation or data request mode. If the filename parameter specifies a data part instead, and at execution time, the contents of that data part include one or more environment variables, then TC will resolve them before trying to use the data as a file name.
  START	The starting position within the data part at which to find the file name. Zero is the beginning of the data.
  LENGTH	The length of data to use from the data part, starting at the START position. Refer to Data Parts for the meaning of a 0 length for a given data part. It may be ignored, it may mean return no data or it may mean take all data from the START position.

  Example:
   
    // Open a flat file for reading
    Open_File_Data( UV1, "Badges.dat" )
    If ( UV1 #== "0" )
     {
      // Read as much as one user variable can hold into UV2
      Set_UV_File_Data ( UV1, UV2, 0 )
     }
    Close_File_Data()
   
  

  Parse_UV

    Parse_UV (uvToBeParsed, DISCARD | uvFirstPart, "delimiter" | CTRL_CODE | uvDelimiter, DISCARD | uvLastPart)
  

  Use this command to split a user variable into parts based on the location of a delimiter character or string.

  The delimiter can be a constant string, one of the predefined control code constants or the contents of a user variable.

  TC locates the delimiter within the user variable specified by the first parameter. All characters before the delimiter are placed in the user variable specified by uvFirstPart and all characters after the delimiter are placed in the user variable specified by uvLastPart. The delimiter is not part of the data put into either uvFirstPart or uvLastPart. 'uvFirstPart' and 'uvLastPart' are cleared before the parsed data is copied - even if nothing is to be copied.

  The keyword DISCARD can be used in place of either uvFirstPart/uvLastPart to indicate that the characters before/after the delimiter should not be stored in any user variable.

  If the delimiter is not found, then uvToBeParsed is copied to uvFirstPart and uvLastPart is cleared.

  If the delimiter is found at the start of uvToBeParsed then uvFirstPart is cleared and uvLastPart is set to all data after the delimiter. Likewise if the delimiter is found at the end of uvToBeParsed, uvLastPart is cleared and uvFirstPart is set to all data before the delimiter.

  If uvToBeParsed is different from uvFirstPart and uvLastPart then the parse operation will not change the contents of uvToBeParsed. However, TC does allow uvFirstPart or uvLastPart to specify the same user variable as uvToBeParsed. In this case, at the end of the parse operation, uvToBeParsed will be set to the appropriate subset of characters from the original value of uvToBeParsed.

  If the delimiter is an empty string or an empty user variable, TC considers it to be found before the first character of uvToBeParsed. In this case, uvFirstPart is cleared and uvLastPart is set equal to uvToBeParsed.

  uvToBeParsed	The user variable in which TC should locate the delimiter character or string.
  uvFirstPart	The user variable into which TC should copy all characters that are found in uvToBeParsed before the delimiter. The specified user variable is cleared before the characters are copied. The keyword DISCARD can be used in place of a user variable name to indicate that these characters should not be stored in any user variable.
  "delimiter"	The third parameter, the delimiter, can be a constant string enclosed in double quotes. The enclosing double quotes are not considered part of the delimiter.
  CTRL_CODE	The third parameter, the delimiter, can also be one of the predefined TC control codes. For a list of valid control codes please see Append_UV_Kbd_Data / Append.
  uvDelimiter	The third parameter, the delimiter, can also be a user variable which contains the delimiter character or string to be found.
  uvLastPart	The user variable into which TC should copy all characters that are found in uvToBeParsed after the delimiter. The specified user variable is cleared before the characters are copied. The keyword DISCARD can be used in place of a user variable name to indicate that these characters should not be stored in any user variable.

  Examples:
   
    // For the first 4 examples uvToBeParsed starts
    // out containing: 1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ
   
    // Use a constant string for a delimiter
    Parse_UV ( uvToBeParsed, uvFirstPart, "EFG", uvLastPart )
    // uvToBeParsed is unchanged
    // uvFirstPart  becomes: 1234567890ABCD
    // uvLastPart   becomes: HIJKLMNOPQRSTUVWXYZ
   
    // Use a user variable for a delimiter
    Set_UV_Kbd_Data ( uvDelimiter, "EFG" )
    Parse_UV ( uvToBeParsed, uvFirstPart, uvDelimiter, uvLastPart )
    // uvToBeParsed is unchanged
    // uvFirstPart  becomes: 1234567890ABCD
    // uvLastPart   becomes: HIJKLMNOPQRSTUVWXYZ
   
    // Delimiter not found
    Parse_UV ( uvToBeParsed, uvFirstPart, "XXX", uvLastPart )
    // uvToBeParsed is unchanged
    // uvFirstPart  becomes: 1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ
    // uvLastPart   becomes:
   
    // Delimiter is an empty UV
    Clear_UV ( uvDelimiter )
    Parse_UV ( uvToBeParsed, uvFirstPart, uvDelimiter, uvLastPart )
    // uvToBeParsed is unchanged
    // uvFirstPart  becomes:
    // uvLastPart   becomes: 1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZ
   
   
    // For the next 4 examples, uvQty starts out containing: 123.75
   
    // Separate the real and fractional part
    Parse_UV(uvQty, uvWholePart, ".", uvFractPart)
    // uvQty       is unchanged
    // uvWholePart becomes: 123
    // uvFractPart becomes: 75
   
    // Just get the whole part; don't store the fractional part anywhere
    Parse_UV(uvQty, uvWholePart, ".", DISCARD)
    // uvQty       is unchanged
    // uvWholePart becomes: 123
   
    // Just get the fractional part; don't store the whole part anywhere
    Parse_UV(uvQty, DISCARD, ".", uvFractPart)
    // uvQty       is unchanged
    // uvFractPart becomes: 75
   
    // Remove the fractional part from uvQty and store it back in uvQty
    Parse_UV(uvQty, uvQty, ".", DISCARD)
    // uvQty becomes 123
   
   
    // The following series of commands shows successive paring down
    // of a user variable containing fields separated by commas
    Set_UV_Kbd_Data ( uvToBeParsed, "1234567890ABCDEFGHIJKLMNO,PQRST,,,UV,WXYZ," )
    Parse_UV ( uvToBeParsed, uvField1, COMMA, uvToBeParsed )
    // uvToBeParsed becomes: PQRST,,,UV,WXYZ,
    // uvField1     becomes: 1234567890ABCDEFGHIJKLMNO
   
    Parse_UV ( uvToBeParsed, uvField2, COMMA, uvToBeParsed )
    // uvToBeParsed becomes: ,,UV,WXYZ,
    // uvField2     becomes: PQRST
   
    Parse_UV ( uvToBeParsed, uvField3, COMMA, uvToBeParsed )
    // uvToBeParsed becomes: ,UV,WXYZ,
    // uvField3     becomes:
   
    Parse_UV ( uvToBeParsed, uvField4, COMMA, uvToBeParsed )
    // uvToBeParsed becomes: UV,WXYZ,
    // uvField4     becomes:
   
    Parse_UV ( uvToBeParsed, uvField5, COMMA, uvToBeParsed )
    // uvToBeParsed becomes: WXYZ,
    // uvField5     becomes: UV
   
    Parse_UV ( uvToBeParsed, uvField6, COMMA, uvToBeParsed )
    // uvToBeParsed becomes:
    // uvField6     becomes: WXYZ
   
    Parse_UV ( uvToBeParsed, uvField7, COMMA, uvToBeParsed )
    // uvToBeParsed becomes:
    // uvField7     becomes:
   
   
  

  Password

    Password ( "password" )
  

  Set the password that will be required for the operator to shut down or change the Trace status of any session processing the script. The Password command can be used at any place in the script, and the last use will define the single password.

  The password is stored un-encrypted in the script file, so anyone with access to the PC can find it if they try. It is not meant as a high-security system, but rather as a way to prevent unintended disruption to the transaction processing system.

  To prevent users from getting to this password, use the password protection provided by the operating system to prevent unauthorized users from getting to the desktop.

  password

  Up to 8 letters and/or numbers that make up the password. The password is not case-sensitive.

  Example:
   
    Password ( "ABC" )
  

  Perform_Fetch / Perform_Fetch2

    Perform_Fetch( OPT_ERROR_LABEL )
    
  Starting in version 3.1.0, the suffix-2 commands were added, and they have added a new first parameter, the ODBC data source alias:
  
    Perform_Fetch2( DataSourceAlias* , OPT_ERROR_LABEL )
  

  This command is used to retrieve the first or next row of the report generated by a Select statement. It is used after the command Perform_Select, or after a free-form SQL statement Begin_SQL has performed a query.

  If the database driver reports an error, processing branches to the label ERROR_LABEL unless you have explicitly redirected the specific SQL error that occurred to another label using the On_Error_Goto command. Some SQL errors are considered by TC to be fatal (see Fatal SQL Errors), and it shuts down after posting an error to the screen and to the error log file.

  If you call Perform_Fetch in a loop until it reaches the end of the data in the report, it encounters a "No Data" return code from the database driver. This causes a branch to the ERROR_LABEL, but it is not considered a serious error (rather, a normal occurrence) and as such, no error is logged to the screen or to the log file (for example, TC2ERRz.LOG). When the "No Data" error is encountered, the data from the last successful fetch (if there was at least one row in the report) is still valid and can be used with the command Append_UV_Select_Data.

  DataSourceAlias*	For the suffix-2 version, the required first parameter is an ODBC database alias (literal or as contents of a user variable) as defined in a Database / DB command. The SQL will be executed against that data source.
  OPT_ERROR_LABEL	The default label to branch to in the event of an error. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends. The label is optional; if not specified, the script will always execute the next command step.

  Example:
   
    Perform_Fetch ( OPT_SQL_error )
    
    Perform_Fetch2 ( DataSourceAlias, OPT_SQL_error )
    
    Call DoCommit()
    
    ...
    Sub DoCommit()
      Declare( theDS ) 
      Set_UV_Data_Part( theDS, LAST_DS_ALIAS ) // Recall the last data source used by other code
      Commit_Changes2( theDS )
    EndSub() 
    
  

  Perform_Insert / Perform_Insert2

    Perform_Insert( OPT_ERROR_LABEL )
    
  Starting in version 3.1.0, the suffix-2 commands were added, and they have added a new first parameter, the ODBC data source alias:
  
    Perform_Insert2( DataSourceAlias* , OPT_ERROR_LABEL )
  

  This is the final command in the series used to INSERT a row (record) into a database table. If the database driver reports an error, processing will branch to the label ERROR_LABEL unless you have explicitly redirected the specific SQL error that occurred to another label using the command On_Error_Goto. These errors can be caused by trying to insert a row where a unique row condition would be violated (for example, you already have such a badge number), an SQL syntax error due to a problem with your script file (for example, miss-spelling a column name), a value range error for a field, and so forth. Some SQL errors are considered by TC to be fatal (see Fatal SQL Errors), and it will shut down after posting an error to the screen and to the error log file.

  See also Insert_DB_Table and Setup_Insert_Field.

  DataSourceAlias*	For the suffix-2 version, the required first parameter is an ODBC database alias (as a literal, or from contents of a user variable) as defined in a Database / DB command. The SQL will be executed against that data source.
  OPT_ERROR_LABEL	The default label to branch to in the event of an error. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends. The label is optional; if not specified, the script will always execute the next command step.

  Example:
   
    Perform_Insert ( OPT_SQL_error )
    
    Perform_Insert2 ( "MyDSAlias", OPT_SQL_error )
    
    Perform_Insert2 ( vInvDS, OPT_SQL_error )
  

  Perform_Select

    Perform_Select( ERROR_LABEL )
  

  This is the final command in the series used to Select columns from a row (record) or rows in a database table. After this command is completed, the command Perform_Fetch can be used to retrieve each row of the output report.

  If the database driver reports an error, processing will branch to the label ERROR_LABEL unless you have explicitly redirected the specific SQL error which occurred to another label using the command On_Error_Goto. Some SQL errors are considered by TC to be fatal (see Fatal SQL Errors), and it will shut down after posting an error to the screen and to the error log file.

  ERROR_LABEL

  The default label to branch to in the event of an error If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends. The label is optional; if not specified, the script will always execute the next command step.

  Example:
   
    Perform_Select ( SQL_error )
  

  Perform_Update

    Perform_Update( ERROR_LABEL )
  

  This is the final command in the series used to UPDATE a row (record) in a database table. If the database driver reports an error, processing will branch to the label ERROR_LABEL unless you have explicitly redirected the specific SQL error that occurred to another label using the On_Error_Goto command. These errors may be due to trying to update a row that does not exist (for example, the WHERE condition excluded all rows), an SQL syntax error due to a problem with your script file (for example, miss-spelling a column name), a value range error for a field, and so forth. Some SQL errors are considered by TC to be fatal (see Fatal SQL Errors), and it will shut down after posting an error to the screen and to the error log file.

  See also Update_DB_Table, Setup_Update_Field, and Update_Where.

  ERROR_LABEL

  The default label to branch to in the event of an error. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends. The label is optional; if not specified, the script will always execute the next command step.

  Example:
   
    Perform_Update ( SQL_error )
  

  Query_Mailbox

    Query_Mailbox ( "mailboxName", uvForNumToRead [, uvForNumToRel [, uvForActive [, uvForCapacity [, uvForLogFileName]]]]  )
    Query_Mailbox ( uvMailboxName, uvForNumToRead [, uvForNumToRel [, uvForActive [, uvForCapacity [, uvForLogFileName]]]]  )
    Query_Mailbox ( uvMailboxName, uvForNumToRead [, uvForNumToRel [, uvForActive [, uvForCapacity [, uvForLogFileName [, uvForPercentFull]]]]]  )
  

  Send a query mailbox request to the DCConnect Server to get information about a particular mailbox. The information that can be returned includes:

  • Number of transactions that have yet to be read from the mailbox

  • Number of transactions that have been read but have not yet been released from the mailbox

  • Indication whether an application is actively reading from the mailbox. The specified user variable is set to "1" if mailbox is active; it is set to "0" otherwise.

  • Capacity of the mailbox. If the DCConnect Server is earlier than October 2004, this value will indicate a number of transactions. Otherwise this will indicate the size of the logfile as a number of bytes.

  • Name of the logfile on disk used to store the transactions for this mailbox (the specified file is located in the %DCCONN%\data directory).

  • If both the DCConnect Server and TC are from October 2004 or later, you can get a sixth value that specifies the percent full that the mailbox is. This will be a value from 0 to 100.

  At a minimum, the first two parameters are required. The last 5 parameters are optional, but if used they must be used in the order shown. If any of the optional parameters are to be used, all preceding optional parameters must also be used. In other words, in order to have the LogFileName returned, you must use all 5 optional parameters (plus the two required parameters).

  "mailboxName"	The name of a mailbox to be queried. This must be defined in the DCConnect configuration. This name is case-sensitive. If not using a user variable for the mailbox name, it must be enclosed in double quotes.
  uvMailboxName	User variable containing the name of the mailbox to be queried.
  uvForNumToRead	User variable in which TC will store the value for the number of transactions to be read
  uvForNumToRel	User variable in which TC will store the value for the number of transactions to be released
  uvForActive	User variable in which TC will store a "1" if the mailbox is active or a "0" if the mailbox is not active. (An active mailbox is one that an application has opened using the DCConnect API DcxOpenMailbox. That application might be a TC script).
  uvForCapacity	User variable in which TC will store the capacity of the mailbox.
  uvForLogFileName	User variable in which TC will store the name of the physical logfile on disk.
  uvForPercentFull	User variable in which TC will store a value from 0-100 indicating what percent of the logfile is currently being used. This parameter is only valid if both TC and the DCConnect Server are from October 2004 or later.

  Examples:
   
    ...
    Name_UV(NEXT_UV, uvMailboxName)
    Name_UV(NEXT_UV, uvNumToRead)
    Name_UV(NEXT_UV, uvNumToRelease)
    Name_UV(NEXT_UV, uvActive)
    ...
   
    // Store the number of transactions to be read for mailbox Sample_DCC in uvNumToRead.
    Query_Mailbox( "Sample_DCC", uvNumToRead)
   
    // Store the number of transactions to be read for mailbox Sample_DCC in uvNumToRead
    // and store the number of transactions to be released in uvNumToRelease.
    Query_Mailbox( "Sample_DCC", uvNumToRead, uvNumToRelease)
   
    // Do the same thing as the previous example, but use a user variable for the
    // mailbox name
    Set_UV_Kbd_Data(uvMailboxName, "Sample_DCC")
    Query_Mailbox( uvMailboxName, uvNumToRead, uvNumToRelease)
   
    // If you only want the Active status, you could actually reuse the
    // same user variable for the last 3 parameter because TC processes
    // them in order; each operation overwrites the previous one.
    Set_UV_Kbd_Data(uvMailboxName, "Sample_DCC")
    Query_Mailbox( uvMailboxName, uvActive, uvActive, uvActive)
    if (uvActive == "0")
     {
      // Flag error because mailbox is no longer active
     }
   
  

  Quit_Subroutines

    Quit_Subroutines()
  

  This command causes TC to remove the stored pointers to the return points of any subroutines that have been called. Call this when you branch from a subroutine back to the main level of the script without allowing the end of the subroutine(s) to run. This prevents the internal subroutine stack from filling with re-entered subroutine return points.

  Note:

  This command does not cause a return from the subroutine(s). Do not execute this command and then allow an EndSubroutine command to be executed; this will cause a stack error.

  Example:
   
    // The script goes to this label when any of several subroutines determines
    // that the processing should start over again for this transaction.
    // This label is in the base level of the script
    // (for example, not in a subroutine).
    Start_Over:
   
      // Quit from any subroutines, thereby cleaning up the stack.
      Quit_Subroutines()
   
      // Do some work....
   
      ...
   
   
    StartSubroutine(Update_Host)
   
      // Do some work....
   
      // Determine that we should start all over again.
      Goto Start_Over
   
      // Do normal work, finally allowing a normal subroutine
      // end and normal return to return point in script.
   
    EndSubroutine()
  

  Reenable_Trace_Via_Restart

    Reenable_Trace_Via_Restart
  

  This command is used to specify that the TC session should use a restart (when idle) as the mechanism for resuming tracing, if tracing has to be suspended because script execution has been slowed on an overloaded/busy Windows system. This creates a fresh connection with the tracing process.

  Example:
   
    Reenable_Trace_Via_Restart
  

  Release_Xact

    Release_Xact()
  

  This command tells DCConnect that it can release the transaction from the DCConnect mailbox. You release the transaction as soon as you have completed all database processing required and have used Commit_Changes to make database changes permanent.

  If you do not release the transaction somewhere in your processing prior to encountering an EndKey command, TC releases it for you and logs an error to the error log and logs the transaction to the transaction log file(for example, TC2XACx.LOG, where x is the controller ID character). If three transactions in a row are logged in this way, TC terminates.

  This command is not applicable when the TC session is operating in remote validation or data request mode. (**) (66)

  Example:
   
    Release_Xact()
  

  Reply_To_Data_Request

    Reply_To_Data_Request ( UV )
    Reply_To_Data_Request ( UV, ERROR_LABEL)
  

  This function allows the TC session to send a reply for a data request that it is servicing. This function is valid only if running in DATA_REQUEST mode.

  The reply to the request is actually routed through DCConnect who makes sure it gets to the originator of the request.

  Data requests and their replies are allowed to be up to 16383 characters in length. By default only user variables 241 through 250 are of this size, it is recommended that the user variable used to build the reply be one of these larger user variables. If the reply never exceeds 235 bytes, any user variable can be used. In addition, the Define_UVs. command can be used to change the number of large user variables that are available.

  UV	The TC user variable containing the reply data that is to be sent to the originator of the request; not to be confused with terminal-resident user variables.
  ERROR_LABEL	The default label to branch to in the event of an error. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control returns to the next command when the subroutine ends. The label is optional; if not specified, the script always execute the next command step.

  Example:
   
    // Send the reply for the data request currently being serviced
   
    Name_UV( UV242, REPLY_BUFFER)
   
    StartMatch ( "STCKRM", TXNDATA, 0, 6 )
   
      // ... steps to parse the data request and build the reply
      // ... in the REPLY_BUFFER
   
      Reply_To_Data_Request( REPLY_BUFFER, Reply_Failed)
   
    EndMatch
  

  Report_Term_State / Report_Terminal_State

    Report_Term_State ( TERMINAL_NAME*, SERVICE_STATE_UV, POLLING_STATE_UV, OPERATION_UV, STEP_UV)
    Report_Term_State ( TERMINAL_NAME*, SERVICE_STATE_UV, POLLING_STATE_UV, OPERATION_UV, STEP_UV, OPT_ERR_LABEL)
  

  Send a report terminal state request to the DCConnect Server to get information about a particular terminal. The state information that is returned maps to the same information that is returned by the DCConnect API DcxReportTerminalState:

  • The returned Service State can be 1 indicating the terminal is in service or it can be 2 indicating the terminal is out of service.

  • The returned Polling State can be 1 indicating the terminal is not being polled or it can be 2 indicating the terminal is being polled.

  • The Operation returned can be any of the following numbers:

    1	DCX_OPER_NOT_IN_USE	Not being used
    2	DCX_OPER_DOWNLOADING	Downloading files to the terminal
    3	DCX_OPER_FLUSHING	Flushing transactions from terminal
    4	DCX_OPER_INITIALIZING	Terminal is being configured
    5	DCX_OPER_NOT_RESPONDING	Terminal not responding
    6	DCX_OPER_BAD_TERMINAL	The attached terminal has a different type than that configured for it; the terminal could not be put in service; or the terminal is generating incorrect responses.
    7	DCX_OPER_TIME_SYNCH	Terminal is currently having its clock updated with the current time.
    8	DCX_OPER_IDLE	Terminal is operational - the current service state and polled state further specify in what state the terminal is.
    9	DCX_OPER_STOPPED	Communications to this terminal have been stopped due to multiple consecutive download failures, transaction logfile filling up, or some other reason.
    10	DCX_OPER_LOAD_QUEUED	One or more download requests are currently pending for this terminal. DCConnect attempts to start as many queued loads as possible once a minute.
    11	DCX_OPER_LOAD_FAILED	A download attempt has failed for this terminal but the download request was queued so that it can be retried. DCConnect attempts to start as many queued loads as possible once a minute.

  • The Step returned can be any of the following numbers but is only relevant when the Operation is 2 (DCX_OPER_DOWNLOADING):

    1	DCX_STEP_SETTING_UP	Download process is initializing
    2	DCX_STEP_FLUSHING	Transactions are being flushed
    3	DCX_STEP_RESET	Cool reset in progress
    4	DCX_STEP_FIXUP_ETS	ETS is being fixed up for loading
    5	DCX_STEP_LOAD_ETS	ETS is being loaded
    6	DCX_STEP_INIT_FILES	Non-ETS files are being initialized
    7	DCX_STEP_PROGRAMS	Transaction program file is loading
    8	DCX_STEP_FASTCLOCK	Fast clocking file is loading
    9	DCX_STEP_VAL_1	Validation file 1 is loading
    10	DCX_STEP_VAL_2	Validation file 2 is loading
    11	DCX_STEP_VAL_3	Validation file 3 is loading
    12	DCX_STEP_VAL_4	Validation file 4 is loading
    13	DCX_STEP_VAL_5	Validation file 5 is loading
    14	DCX_STEP_VAL_6	Validation file 6 is loading
    15	DCX_STEP_MESSAGES	Message file is loading
    16	DCX_STEP_KEYCODES	Keyboard codes file is loading
    17	DCX_STEP_PFKEYS	PF Key file is loading
    18	DCX_STEP_FIXUP_CFR	CFR file is being fixed up for loading
    19	DCX_STEP_LOAD_CFR	CFR file is loading
    20	DCX_STEP_GRAPHICS	Graphics file is being loaded
    21	DCX_STEP_VAL_MAP	Validation map file is loading
    22	DCX_STEP_VAL_EXT	Extended validation files are loading
    23	DCX_STEP_START_TERM	Terminal is being started after loading

  Note: Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "15", "ShippingMailbox", and so forth) or as the current value of a TC user variable by using the user variable's name or the notation UVn, where n ranges from one to 250 or the maximum defined by Define_UVs.

  TERMINAL_NAME*	Literal terminal name or the User variable containing the name of the terminal to be queried.
  SERVICE_STATE_UV	User variable in which TC will store the value for the Service State. See above for the values that can be returned.
  POLLING_STATE_UV	User variable in which TC will store the value for the Polling State. See above for the values that can be returned.
  OPERATION_UV	User variable in which TC will store the value for the Operation. See above for the values that can be returned.
  STEP_UV	User variable in which TC will store the value for the Step. See above for the values that can be returned.
  OPT_ERR_LABEL	If an error label is provided, control will branch to this label if an error occurs when trying to get the terminal state (e.g. the DCConnect Server is not running). The data part LAST_ERROR will contain the error code. If the label name is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends. The label is optional; if not specified, the script will always execute the next command step - unless the error causes TC to terminate.

  Examples:
   
    ...
    Declare ( uvService )
    Declare ( uvPolling )
    Declare ( uvOperation )
    Declare ( uvStep )
    ...
   
    // Don't let DCConnect unavailability end the TC session
    No_Terminate_From_DCConnect
  
    // Get the state for the terminal named "Dock_Door_1"
    Report_Term_State( "Dock_Door_1", uvService, uvPolling, uvOperation, uvStep, ReportError )
  
    // Act on the information returned
  
  
    ...
  ReportError:
    
    // Handle error trying to get report
   
   

  Report_Term_Version / Report_Terminal_Version

    Report_Term_Version ( TERMINAL_NAME*, VERSION_UV)
    Report_Term_Version ( TERMINAL_NAME*, VERSION_UV, OPT_ERR_LABEL)
  

  Send a report terminal version request to the DCConnect Server to get the version of the DCConnect Client or firmware running in a particular terminal. The version information that is returned is the same information that is returned by the DCConnect API DcxReportTerminalVersion.

  Note: Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "15", "ShippingMailbox", and so forth) or as the current value of a TC user variable by using the user variable's name or the notation UVn, where n ranges from one to 250 or the maximum defined by Define_UVs.

  TERMINAL_NAME*	Literal terminal name or the User variable containing the name of the terminal to be queried.
  VERSION_UV	User variable in which TC will store the returned version string.
  OPT_ERR_LABEL	If an error label is provided, control will branch to this label if an error occurs when trying to get the terminal version (e.g. the DCConnect Server is not running). The data part LAST_ERROR will contain the error code. If the label name is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends. The label is optional; if not specified, the script will always execute the next command step - unless the error causes TC to terminate.

  Examples:
   
    ...
    Declare ( uvVersion )
    ...
   
    // Don't let DCConnect unavailability end the TC session
    No_Terminate_From_DCConnect
  
    // Get the version for the terminal named "Dock_Door_1"
    Report_Term_Version( "Dock_Door_1", uvVersion, ReportError )
  
    // Act on the information returned
  
  
    ...
  ReportError:
    
    // Handle error trying to get report
   
   

  Resize_Both_Panes

    Resize_Both_Panes
  

  Use this command to tell TC to resize both the Messages pane and the Execution pane whenever the main TC window is resized. As of the 3.0.8d release of TC in September 2012, this is now the default behavior if none of the Resize_* commands are used in the script.

  This command may be placed anywhere in the script file to override the default operation of TC.

  Example:
   
    // Tell TC to resize the Messages pane and Execution pane whenever the TC window is resized
    Resize_Both_Panes
  

  Resize_Execution_Pane_Only

    Resize_Execution_Pane_Only
  

  Use this command to tell TC to resize the Execution pane and not the Messages pane whenever the main TC window is resized. This used to be the default behavior of TC. But as of the 3.0.8d release in September 2012, the default behavior was changed to resize both panes together.

  This command may be placed anywhere in the script file to override the default operation of TC.

  Example:
   
    // Tell TC to resize the Execution pane and not the Messages pane whenever the TC window is resized
    Resize_Execution_Pane_Only
  

  Resize_Messages_Pane_Only

    Resize_Messages_Pane_Only
  

  Use this command to tell TC to resize the Messages pane and not the Execution pane whenever the main TC window is resized. As of the 3.0.8d release in September 2012, the default behavior was changed to resize both panes together.

  This command may be placed anywhere in the script file to override the default operation of TC.

  Example:
   
    // Tell TC to resize the Messages pane and not the Execution pane whenever the TC window is resized
    Resize_Messages_Pane_Only
  

  Restart_TC

    Restart_TC ()
  

  This command is used to end the execution of the TC session and spawn a replacment process, using the same command line arguments. The logoff script is executed, the connections to DCConnect, the database, and PCOMM are dropped. If the Select cursor is open, it is automatically closed. A ROLLBACK is done on any non-committed SQL unit of work.

  No automatic transaction release is issued to DCConnect. If your script has not released the transaction, DCConnect presents the transaction again the next time TC is started.

  There are no parameters.

  Example:
   
    Restart_TC()
  

  Return

    Return()
  

  This command may be used to return from a subroutine without encountering the EndSubroutine command.

  Example:
   
    Return()
  

  Rollback_Changes / Rollback_Changes2

    Rollback_Changes( OPT_ERROR_LABEL )
    
  Starting in version 3.1.0, the suffix-2 commands were added, and they have added a new first parameter, the ODBC data source alias:
  
    Rollback_Changes2( DataSourceAlias* , OPT_ERROR_LABEL )
  

  This command performs a database ROLLBACK, which removes the changes to the tables made in the current unit of work.

  The classic example of the use of ROLLBACK is to make sure your database remains consistent after a set of changes which affect multiple tables. If you are moving stock from one warehouse to another, you want to make sure that the quantity subtracted from one is added to the other before you complete the transaction. You should do an update that subtracts stock from one warehouse, and then do an update that adds stock to the other warehouse. Use the command Commit_Changes only after the second update has worked successfully. If the second update did not work, you should do a ROLLBACK to un-do the first update, or else some of your stock will disappear from your database even though it is actually there.

  A COMMIT will be done for you automatically at the end of the script (EndKey / EndMatch / EndVal/...) if you have made any database changes and have not done a Rollback_Changes to remove them. However, this is considered an error in your script and an error message will be logged.

  DataSourceAlias*	For the suffix-2 version, the required first parameter is an ODBC database alias ( as a literal or from contents of a user variable) as defined in a Database / DB command. The SQL will be executed against that data source.
  ERROR_LABEL	Branch to this label if a non-fatal SQL error occurs while attempting the ROLLBACK. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends. The label is optional; if not specified, the script will always execute the next command step.

  Example:
   
    Rollback_Changes( Rollback_Error )
  

  Run_Without_Connect

    Run_Without_Connect()
  

  This command lets you specify that a TC session should be able to run (for example, read from and respond to data collection terminals, and so forth) even when there is no connection to the database. See Processing when the Database or Host Is Unavailable for details of how this can be useful.

  Example:
   
    Run_Without_Connect()
  

  Run_Without_Session

    Run_Without_Session()
  

  This command lets you specify that a TC session should be able to run (for example, read from and respond to data collection terminals, and so forth) even when there is no connection to the host terminal emulation session. This command may appear anywhere in the script to set the mode of operation for the entire TC session.

  Session_Connect, Communication_Disconnect, Communication_Connect, and On_Error_Goto and the data part SESSION_STATUS to build error-tolerance and recovery into your host-oriented scripts.

  Example:
   
    Run_Without_Session()
  

  Save_UVs

    Save_UVs()
  

  This command saves to disk storage the contents of user variables UV1 through UV20 for the current terminal. These user variables can now be restored to this state by a subsequent use of the command Load_UVs. This allows for a continuity of data processing for individual terminals, even though this TC session may be handling similar interspersed transactions from multiple terminals in succession.

  For example, because the 7526 and 7527 terminal can send a maximum transaction size of only 104 characters, you may need to be able to combine 2 or more transactions from a terminal into one larger transaction to the database. When your script recognizes the first transaction of the series coming in (based on its key ID or a matching data identifier; see Startkey and StartMatch commands), it can save this first part of the overall data in one of the TC user variables (UV1 through UV20 are valid for this purpose). Then when the second (and any further) parts of the overall data come in succeeding transactions, the earlier parts can be loaded from disk and combined with the new data for further processing.

  The user variable data is saved in files that are uniquely named based on the terminal's physical address and the TC session's controller ID. A physical terminal can have more than one file containing user variable data on your personal computer if that terminal sends transactions to more than one TC session. For a particular TC session, there is only one file for a particular physical terminal. All transactions handled from that terminal must be processed to cooperatively use the 20 user variables that can be saved and re-loaded.

  Note: Due to the way terminal addresses are reported by DCConnect and the way the file extension is derived, the file extension for RF terminal addresses 100-126 is the same as for RF terminals 0-26. It is recommended that you do not use this function for RF terminals with addresses in both ranges at the same time. In Data Request mode, if the originator of the data request is an application instead of a terminal, the first three characters of the originator name are used for the extension.

  User variables UV21 and up are not stored or retrieved with the Save_UVs / Load_UVs commands. These other user variables are always shared between all terminals and all transactions processed through the TC session. This allows for the possibility of inter-terminal communication using these shared memory areas.

  Example:
   
    // Part A of a big transaction comes in with the
    // identifier 'PTA' as the first 3 characters of data
    StartMatch ( "PTA", TXNDATA, 0, 3 )
   
      // Clear UV1 and append it to 98 characters
      // of the transaction that follow the PTA identifier,
      // then save UV1-UV20 and release the transaction.
      Clear_UV( UV1 )
      Append_UV_Xact_Data( UV1, TXNDATA, 3, 98 )
      Save_UVs()
      Release_Xact()
   
    EndMatch()
   
    // Part B of a big transaction comes in with the
    // identifier 'PTB' as the first 3 characters of data.
    // This is the final part of the transaction.
    StartMatch ( "PTB", TXNDATA, 0, 3 )
   
      // Load the stored user variables for this
      // terminal.  This will bring in the Part A
      // data that was stored from the first transaction
      Load_UVs()
   
      // We have an error if, for some reason, we received
      // part B but have no part A.  If part A, stored in UV1,
      // is missing (that is, UV1 is empty), then goto error
      // recovery.  Use a cleared UV30 as a test against UV1.
      Clear_UV( UV30 )
      If ( UV1 == UV30)
        Goto PART_A_MISSING
   
      // Clear UV2 and append it to 70 characters
      // of the transaction that follow the PTB identifier,
      // then proceed to do remaining processing.
      Clear_UV( UV2 )
      Append_UV_Xact_Data( UV2, TXNDATA, 3, 70 )
      Release_Xact()
   
      // Do other processing with the data in UV1 and UV2....
   
    EndMatch()
  

  Screen_Width

    Screen_Width ( WIDTH )
  

  This command changes the default screen width from 80 to a different width as specified. TC does not know and cannot control the display size configured for the PCOMM session and supported by the host. For any TC script command that uses row and column coordinates to work properly, the proper screen width must be made known. If your session uses an 80-column screen, the default will work and you do not need to use this command.

  WIDTH

  The host session screen width as configured in PCOMM and supported by the host system.

  Example:
   
    Screen_Width( 132 )
  

  Select_Column

    Select_Column( COLUMN )
  

  This is the second command in the series of commands used to do a Select from a table. It specifies which columns or column function from the table you want to have in the output report. This command can be repeated up to 255 times to specify the columns or column functions you need in the output. The order in which you specify the columns in the successive Select_Column calls determines the order in which the output columns will be presented (for use by Append_UV_Select_Data).

  COLUMN

  The table column name or a column function (for example, in DB2, MAX( QUANTITY )). If using DB2, refer to the SQL Reference, Chapter 4. Functions. Otherwise consult the documentation for your database type.

  Example:
   
    Select_Column( QUANTITY )
    Select_Column( LOCATION )
  

  Select_From_DB_Table

    Select_From_DB_Table( QUALIFIER.TABLE_NAME* )
  

  This is the first command of the series required to do a Select (query) from a table in the database. The WHERE, GROUP BY, HAVING, and SORT BY clauses are optional. Depending on your needs, 1, 2, 3, or all 4 of these clauses can be used. See Select Statement for further details.

  *The parameter can be specified as a quoted or unquoted string, a user variable, or a data part. Prior to version 3.1.0e, this could only be a quoted or an unquoted string.

  QUALIFIER	An optional qualifier in case the table is associated with a user ID other than that which is logged on to the database at this workstation. Leave this off if the tables are owned by the current user ID.
  TABLE_NAME	The name of the table within the database.

  Examples:
   
    // Use the qualifier and table directly
    Select_From_DB_Table( PERSONNEL.EMPLOYEES )
  
    // Use a variable for the parameter
    Set ( UV1, "PERSONNEL.EMPLOYEES" )
    Select_From_DB_Table ( UV1 )
  
  

  Select_Group_By

    Select_Group_By( COLUMN )
  

  This is one of the 4 optional commands (SELECT_WHERE, SELECT_GROUP_BY, SELECT_ORDER_BY, SELECT_HAVING) in the series used to do a Select from a table. It specifies that the result table from the previous clause should be grouped such that all rows in the group have the same value for COLUMN. In other words, produce a sub-report for each different value of the column in the SELECT_GROUP_BY clause.

  COLUMN

  The table column name or a column function (for example, in DB2, MAX( QUANTITY )). If using DB2, refer to the SQL Reference, Chapter 4. Functions. Otherwise consult the documentation for your database type.

  Example:
   
    Select_Group_By( SKILL_LEVEL )
  

  Select_Having

    Select_Having( COLUMN, COL_TYPE, COMPARISON, DATA_PART, START, LENGTH )
    Select_Having( COLUMN, COL_TYPE, COMPARISON, DATA_PART, START, LENGTH,
                      PREFIX )
    Select_Having( COLUMN, COL_TYPE, COMPARISON, DATA_PART, START, LENGTH,
                      PREFIX, SUFFIX )
  

  This is one of the 4 optional commands (SELECT_WHERE, SELECT_GROUP_BY, SELECT_ORDER_BY, SELECT_HAVING) in the series used to Select a row (record) or rows from a table. This command specifies the HAVING condition for the Select. Refer to the documentation for your database software for details about how to use the HAVING clause.

  COLUMN	The table column name to be compared against other data.
  COL_TYPE	The type of data stored in the column: NUMERIC, CHARACTER, TIME, DATE, or TIMESTAMP. The type tells TC whether to put quotes around the data (CHARACTER or time/date types) and whether to add delimiters and the century to time/date types. For time/date types, the input data can be in the form sent by the terminal, or it can already have delimiters in place. Data for a TIME type column must be in the form HHMMSS (as it comes from the terminal), HH:MM:SS, or 'HH:MM:SS'. Data for a DATE type column must be in the form YYMMDD (as it comes from the terminal), YYYY/MM/DD, or 'YYYY/MM/DD'. Data for a TIMESTAMP type column must be in the form YYMMDDHHMMSS (as it comes from the terminal), YYYY-MM-DD-HH.MM.SS, or 'YYYY-MM-DD-HH.MM.SS'.
  COMPARISON	The logical comparison operator used between the column name and the data (PREFIX+DATA_PART+SUFFIX). Possible values include =, <>, >, >=, <=, <.
  DATA_PART	This specifies one of various predefined parts of the terminal transaction or other information that is used for the Select Having criteria. The predefined parts for this parameter are shown in Data Parts. The data parts that are valid vary depending on whether the TC session is currently running in transaction, validation or data request mode.
  START	The starting position within the data part. Zero is the beginning of the data.
  LENGTH	The length of data to use from the data part, starting at the START position. Refer to Data Parts for the meaning of a 0 length for a given data part. It may be ignored, it may mean return no data or it may mean take all data from the START position.
  PREFIX	An optional string to append as a prefix to the data from the DATA_PART. The data used for the command is formulated by appending the three elements: PREFIX+DATA_PART+SUFFIX For example, to specify the COLUMN must be equal to a constant value of 12, you can specify the DATA_PART as NULL and set the PREFIX to 12, and not specify the SUFFIX. The result of PREFIX+DATA_PART+SUFFIX will be the value 12. If you do not want a prefix but do want a suffix, specify the PREFIX to be NULL. You cannot have a suffix without a prefix as a place holder in the command.
  SUFFIX	An optional string to append as a suffix to the data from the DATA_PART. The data used for the command is formulated by appending the three elements: PREFIX+DATA_PART+SUFFIX The SUFFIX can be useful to add an AND clause to the condition (for example, AND WAREHOUSE=5). You can specify the SUFFIX as NULL, which is equivalent to not specifying a SUFFIX at all and simply ending the command string with the ending ')'.

  Example:
   
    //Select the row(s) where PART_NUMBER equals the 2nd ';' delimited
    //field of the transaction AND the WAREHOUSE column in the table
    //is equal to 5 (this last AND clause is contained in the SUFFIX,
    //after a NULL PREFIX).
    Select_Having( PART_NUMBER, NUMERIC, = , TXNFIELD2, 0, 0, NULL, AND WAREHOUSE=5 )
   
    // You can also put the AND clause as a prefix, reversing the position
    // of the word 'AND' to match and leaving off the suffix:
    Select_Having( PART_NUMBER, NUMERIC, = , TXNFIELD2, 0, 0, WAREHOUSE=5 AND)
  

  Select_Order_By

    Select_Order_By( COLUMN )
  

  This is one of the four optional commands (SELECT_WHERE, SELECT_GROUP_BY, SELECT_HAVING, SELECT_ORDER_BY) in the series used to do a Select from a table. It specifies the order in which to sort the results report, using the values in COLUMN as the sorting criteria. The default sorting is in ascending order, but can be changed to descending by adding DESC to the column specification.

  COLUMN

  The table column name by which to sort.

  Example:
   
    // Put in ascending order of BADGE_NUMBER
    Select_Order_By( BADGE_NUMBER )
   
    // or
    Select_Order_By( BADGE_NUMBER ASC )
   
    // Order descending
    Select_Order_By( SKILL_LEVEL DESC )
  

  Select_Where

    Select_Where( COLUMN, COL_TYPE, COMPARISON, DATA_PART, START, LENGTH )
    Select_Where( COLUMN, COL_TYPE, COMPARISON, DATA_PART, START, LENGTH,
                     PREFIX )
    Select_Where( COLUMN, COL_TYPE, COMPARISON, DATA_PART, START, LENGTH,
                     PREFIX, SUFFIX )
  

  This is one of the 4 optional commands (SELECT_WHERE, SELECT_GROUP_BY, SELECT_ORDER_BY, SELECT_HAVING) in the series used to Select a row (record) or rows from a table. This command specifies the WHERE condition for the select (for example, the criteria for selecting which row or rows should have the columns specified in Select_Column calls brought into the report).

  COLUMN	The table column name to be compared against other data.
  COL_TYPE	The type of data stored in the column: NUMERIC, CHARACTER, TIME, DATE, or TIMESTAMP. The type tells TC whether to put quotes around the data (CHARACTER or time/date types) and whether to add delimiters and the century to time/date types. For time/date types, the input data can be in the form sent by the terminal or it can already have delimiters in place. Data for a TIME type column must be in the form HHMMSS (as it comes from the terminal), HH:MM:SS, or 'HH:MM:SS'. Data for a DATE type column must be in the form YYMMDD (as it comes from the terminal), YYYY/MM/DD, or 'YYYY/MM/DD'. Data for a TIMESTAMP type column must be in the form YYMMDDHHMMSS (as it comes from the terminal), YYYY-MM-DD-HH.MM.SS, or 'YYYY-MM-DD-HH.MM.SS'.
  COMPARISON	The logical comparison operator used between the column name and the data (PREFIX+DATA_PART+SUFFIX). Possible values include =, <>, >, >=, <=, <.
  DATA_PART	This specifies one of various predefined parts of the terminal transaction or other information that will become the criteria for the Select Where clause. The predefined parts for this parameter are shown in Data Parts. The data parts that are valid vary depending on whether the TC session is currently running in transaction, validation or data request mode. If the datapart is empty (typically a user variable or transaction field) it will be put into the SQL string as an empty string ('') for CHARACTER columns or as NULL for any other type of column.
  START	The starting position within the transaction data part. Zero is the beginning of the data.
  LENGTH	The length of data to use from the data part, starting at the START position. Refer to Data Parts for the meaning of a 0 length for a given data part. It may be ignored, it may mean return no data or it may mean take all data from the START position.
  PREFIX	An optional string to append as a prefix to the data from the DATA_PART. The data used for the command is formulated by appending the three elements: PREFIX+DATA_PART+SUFFIX For example, to specify that the COLUMN must be equal to a constant value of 12, you can specify the DATA_PART as NULL and set the PREFIX to 12, and not specify the SUFFIX. The result of PREFIX+DATA_PART+SUFFIX will be the value 12. If you do not want a prefix but do want a suffix, specify the PREFIX to be NULL. You cannot have a suffix without a prefix as a place holder in the command.
  SUFFIX	An optional string to append as a suffix to the data from the DATA_PART. The data used for the command is formulated by appending the three elements: PREFIX+DATA_PART+SUFFIX The SUFFIX can be useful to add an AND clause to the condition (for example, AND WAREHOUSE=5). You can specify the SUFFIX as NULL, which is equivalent to not specifying a SUFFIX at all and simply ending the command string with the ending ')'.

  Examples:
   
    // A simple WHERE condition selecting those rows where the PART_NUMBER
    // column value equals the text in the second delimited transaction field.
    // If the DCT sent this as an empty field (i.e. ";;") this will yield
    //  'WHERE PART_NUMBER =
    Select_Where ( PART_NUMBER, NUMERIC, = , TXNFIELD2, 0, 0 )
   
    // Select the row(s) where PART_NUMBER equals the 2nd ';'-delimited field
    // of the transaction AND the WAREHOUSE column in the table is equal to 5
    // (this last AND clause is contained in the SUFFIX, after a NULL PREFIX.
    Select_Where ( PART_NUMBER, NUMERIC, = , TXNFIELD2, 0, 0, NULL, AND WHERE WAREHOUSE=5 )
   
    // Do the same thing, but put the warehouse specification in a prefix
    // (no suffix is used)
    Select_Where ( PART_NUMBER, NUMERIC, = , TXNFIELD2, 0, 0, AND WHERE WAREHOUSE=5 )
  

  Send_Host_Data_Part

    Send_Host_Data_Part( DATA_PART, START*, LENGTH*, ROW*, COL*, ERROR_LABEL )
  

  This command is synonymous with Send_Host_Xact_Data.

  Send data to the host screen from the incoming transaction record or from any other data part, including TC user variables. Send_Host_UV_Data can be used to send only the entire contents of a user variable, this command can be used to send either all or a portion of the user variable's contents.

  This command cannot be used in a StartLogon...EndLogon or StartLogoff...EndLogoff sequence because the command requires data from the DCConnect transaction record that is not available when the StartLogon...EndLogon or StartLogoff...EndLogoff sequence executes.

  See Screen_Width if your host session runs in other than 80-column mode.

  Note:

  Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a TC user variable by using the user variable's name or the notation UVn, where n ranges from 1 to 250 or the maximum defined by Define_UVs.

  DATA_PART	This specifies one of various predefined parts of the terminal transaction or other information that becomes part of the data appended to the target user variable. The predefined parts are listed in Data Parts. The data parts that are valid vary depending on whether the TC session is currently running in transaction, validation or data request mode.
  START*	The starting position within the selected data part. Zero is the beginning of the data.
  LENGTH*	The length of data to use from the data part, starting at the START position. Refer to Data Parts for the meaning of a 0 length for a given data part. It may be ignored, it may mean return no data or it may mean take all data from the START position.
  ROW*	The target row on the host screen. The top row is row one. Set ROW and COL to 0 to copy data to the current cursor position.
  COL*	The target column on the host screen. The left-most column is column 1. Set ROW and COL to 0 to copy data to the current cursor position.
  ERROR_LABEL	An optional label to branch to when TC finds that the data or control character cannot be input due to a keyboard locked condition or the host screen being busy for an extended period of time. If no label is provided, TC logs an error and terminate if a locked or busy error occurs. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends.

  Note:

  No range checking is done for row and column parameters. You must use valid values based on the size of the emulation session set up in CM.

  Examples:
   
    // Send all of UV2 to the host screen, starting at the current
    // cursor location
    Send_Host_Data_Part ( UV2, 0, 0, 0, 0, ERROR_1 )
   
    // Send 10 characters from incoming transaction, starting at offset 5,
    // to row 1, column 1
    Send_Host_Data_Part ( TXNDATA, 5, 10, 1, 1, ERROR_2 )
   
    // Send 15 characters from incoming transaction, starting at offset 5,
    // to a row specified by the value of UV30, always at column 1
    Send_Host_Data_Part ( TXNDATA, 5, 10, UV30, 1, ERROR_2 )
  

  Send_Host_Kbd_Data

    Send_Host_Kbd_Data  ( "String", , LOCKED_OR_BUSY_LABEL  )
    Send_Host_Kbd_Data  ( NumericConstant, LOCKED_OR_BUSY_LABEL  )
    Send_Host_Kbd_Data  ( CNTL_FUNC_KEY , LOCKED_OR_BUSY_LABEL )
  

  Transmits a keycode to the host session or places a character string at the current cursor position of the host session screen. Use the command Set_Cursor to change the cursor position if necessary before issuing this command.

  "String"	A literal string enclosed in double quotes. The maximum size of the string is 255 characters.
  NumericConstant	Numeric constants do not have to be enclosed in double quotes and can be any base 10 number, optionally having a leading negative sign and optionally having a decimal point.
  CNTL_FUNC_KEY	An identifier representing the key to be transmitted to the host session. The following are valid identifiers representing the supported keys (not case sensitive). These keys are valid for both 3270 and 5250 emulation: ENTER LEFT_TAB NEW_LINE RIGHT_TAB CLEAR CURSOR_LEFT DELETE CURSOR_RIGHT INSERT CURSOR_UP ERASE_EOF CURSOR_DOWN PRINT HOME RESET END ERASE_INPUT SYSTEM_REQUEST ATTENTION JUMP (set focus under Presentation Manager) PF1 to PF24 The following are for 5250 emulation only: PAGE_UP SPACE PAGE_DOWN HELP FIELD- FIELD_EXIT FIELD+ The following are for 3270 only: SCR_LOCK PA1 NUM_LOCK PA2 CAPS_LOCK PA3 WORD_DELETE
  LOCKED_OR_BUSY_LABEL	An optional label to branch to when TC finds that the data or control character cannot be input due to a keyboard locked condition or the host screen being busy for an extended period of time. If no label is provided, TC will log an error and terminate if a locked or busy error occurs. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends.

  Examples:
   
    //  Put ABCDE at the current cursor position on the screen.
    Send_Host_Kbd_Data ("ABCDE", BAD_INPUT )
   
    //  Put 12345 at the current cursor position on the screen.
    Send_Host_Kbd_Data (12345, BAD_INPUT )
   
    //  "Press" the Enter key; control keys must be performed
    //  on separate commands from text data.
    Send_Host_Kbd_Data (ENTER, BAD_INPUT )
  

  Send_Host_UV_Data

    Send_Host_UV_Data( UV, LOCKED_OR_BUSY_LABEL )
  

  Copy the contents of a TC user variable to the host screen at the current cursor position. The entire user variable contents are sent.

  UV

  The TC user variable.

  LOCKED_OR_BUSY_LABEL

  An optional label to branch to when TC finds that the data or control character cannot be input due to a keyboard locked condition or the host screen being busy for an extended period of time. If no label is provided, TC will log an error and terminate if a locked or busy error occurs. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends.

  Example:
   
    // Send UV 1 contents to host screen at current cursor position
    Send_Host_UV_Data( UV1,  LOCKED_OR_BUSY_LABEL )
  

  Send_Host_Xact_Data

    Send_Host_Xact_Data( DATA_PART, START*, LENGTH*, ROW*, COL*, ERROR_LABEL )
  

  This function is an alias for Send_Host_Data_Part. Refer to Send_Host_Data_Part for a full description of this function.

  Send_Named_Term_UV_Data / Send_Named_Terminal_UV_Data

    Send_Named_Term_UV_Data( TERM_NAME, UV, TERMUV )
    Send_Named_Term_UV_Data( TERM_NAME, UV, TERMUV, MODE )
    Send_Named_Term_UV_Data( TERM_NAME, UV, TERMUV, MODE, ERR_LABEL )
    Send_Named_Term_UV_Data( TERM_NAME, UVa, TERMUV1, UVb, TERMUV2,..., UVx, TERMUVn )
    Send_Named_Term_UV_Data( TERM_NAME, UVa, TERMUV1, UVb, TERMUV2,..., UVx, TERMUVn, MODE )
    Send_Named_Term_UV_Data( TERM_NAME, UVa, TERMUV1, UVb, TERMUV2,..., UVx,
                                         TERMUVn, MODE, ERR_LABEL )
  

  This function is the same as Send_Term_UV_Data except that the terminal name is explicitly specified as the first parameter. Refer to Send_Term_UV_Data for a full description of this function.

  Send_Term_Data / Send_Terminal_Data

    Send_Term_Data( FROM_ROW*, FROM_COL*, LENGTH*, TERM_UV* )
    Send_Term_Data( FROM_ROW*, FROM_COL*, LENGTH*, TERM_UV*, MODE )
    Send_Term_Data( FROM_ROW*, FROM_COL*, LENGTH*, TERM_UV*, MODE, ERR_LABEL )
  

  Copy data from the host screen and send it directly to a terminal user variable.

  See Screen_Width if your host session runs in other than 80-column mode.

  Note:

  Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a TC user variable by using the variable's alias or the notation UVn, where n ranges from 1 to 250 or the maximum defined by Define_UVs.

  FROM_ROW*	The host screen row from which the data will be copied. The top row is row 1.
  FROM_COL*	The host screen column from which the data will be copied. The left-most column is column 1.
  LENGTH*	The length of data to be copied from the host row and column starting position. The maximum value is 118 characters.
  TERM_UV*	The current DCTs user variable number. (**) (69)
  MODE	To facilitate synchronization between TC and the terminal transaction program, the Send_Term_UV_Data command allows you to specify whether the operation should be done SYNCHronously (TC blocks execution until DCConnect is finished with the request to set the user variable) or ASYNCHronously (TC uses a separate thread to send the data, not waiting in the main task for DCConnect to finish sending each user variable). This optional parameter can be specified as ASYNCH or SYNCH. The default mode is ASYNCH.
  ERR_LABEL	An optional label to branch to when TC encounters an error when trying to send the data to the DCT. For example, an RF terminal may have moved out of range or may have been turned off by the operator. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends. This error label has an effect only if the MODE is specified as SYNCH. ASYNCH sends that result in errors does not cause a branch/call to the ERR_LABEL. Note: TC does two retries when sending data to the DCTs. DCConnect does its own retries and there is little need to program your own retry loop unless it is absolutely required that you get the data to the terminal.

  Example:
   
    // Send host screen data from row 5, column 12 for length 20
    // to user variable 10 at the data collection terminal.
    Send_Term_Data( 5, 12, 20, 10 )
   
    // Send host screen data from the row specified by UV1, column 12
    // for length 20 to a user variable at the data collection terminal
    // as specified in UV2.
    // Call the subroutine SUBR_FAILED_SEND if the data could not be
    // sent (this subroutine may log an error report into the database).
    Send_Term_Data( UV1_VALUE, 12, 20, UV2_VALUE, SYNCH, SUBR_FAILED_SEND )
  

  Send_Term_IResp / Send_Terminal_IResp

    Send_Term_IResp( RESPONSE )
    Send_Term_IResp( RESPONSE, BEEP, DURATION, "Message" )
    Send_Term_IResp( RESPONSE, BEEP, DURATION, DATA_PART, START*, LENGTH*)
  

  Send a terminal the response to an interactive (**) (68) transaction. Optionally, the terminal beeper, message display duration, and terminal display message text can be specified. The message text can come from a TC data part or from a literal, constant string in quotes.

  If the optional parameters are not specified, the defaults are:

  • No terminal beep.
  • Message shown for non-prompt message timeout period.
  • Message is standard system message set in terminal configuration.

  Note: Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a TC user variable by using the user variable's name or the notation UVn, where n ranges from 1 to 250 or the maximum defined by Define_UVs.

  RESPONSE	The response you want sent to the terminal. Choices are 1 or 0 (positive or negative, respectively), which can also be specified in the command as POSITIVE or NEGATIVE.
  BEEP	Specify BEEP or NO_BEEP to control terminal beeper when interactive response is received.
  DURATION	Specify TIMED to use the Non-prompt message timeout or OPERATOR to have the message left on the screen until the operator presses some function key.
  DATA_PART	This specifies one of various predefined parts of the terminal transaction or other data that will become the string used for the operator message at the data collection terminal. Data parts are listed in Data Parts. The data parts that are valid vary depending on whether the TC session is currently running in transaction, validation or data request mode.
  START*	The starting position within the data part. 0 is the beginning of the data.
  LENGTH*	The length of data to use from the data part, starting at the START position. Refer to Data Parts for the meaning of a 0 length for a given data part. It may be ignored, it may mean return no data or it may mean take all data from the START position.
  "Message"	The DATA_PART/START/LENGTH parameters for operator message can be omitted and replaced with a literal string presented in double-quote marks.

  Example:
   
    // Send positive response if transaction mode is not Buffered (B)
    // and not terminated-buffered (T) (that is, it is interactive).
    If ( MODE(0, 1) != "B")
      If ( MODE(0, 1) != "T")
        Send_Term_IResp( POSITIVE, BEEP, TIMED, "Input accepted" )
  

  Send_Term_UV_Data / Send_Terminal_UV_Data

    Send_Term_UV_Data( UV, TERMUV )
    Send_Term_UV_Data( UV, TERMUV, MODE )
    Send_Term_UV_Data( UV, TERMUV, MODE, ERR_LABEL )
    Send_Term_UV_Data( UVa, TERMUV1, UVb, TERMUV2, ..., UVx, TERMUVn )
    Send_Term_UV_Data( UVa, TERMUV1, UVb, TERMUV2, ..., UVx, TERMUVn, MODE )
    Send_Term_UV_Data( UVa, TERMUV1, UVb, TERMUV2, ..., UVx,
                                TERMUVn, MODE, ERR_LABEL )
   
    Send_Named_Term_UV_Data( TERM_NAME, UV, TERMUV )
       .
       .
       .
  

  Send the contents of one or more TC user variables to the specified user variables on a DCT (**) (69). Unless the optional Send_Named_Term.... version is used, the data is sent to the same terminal from which the current transaction or validation request originated. The Send_Named_Term_UV_Data version of this command allows you to specify any terminal you desire as the recipient. This is useful, for example, when a host application may want to set a terminal user variable as a flag to change the terminal's processing.

  You can specify up to 15 sets of source TC user variables (UVx) and target DCT user variables. The sending of multiple user variables in one command is especially useful for working with the 7524 RF terminal running its version of Extended Terminal Services; response time for the 7524 is greatly improved by sending a few very large packets rather than many small ones. The multiple user variables method can be used with any DCT type that support setting of user variables.

  Note that prior to TC fixpack 1.40 E the limit was 10 user variable sent at one time.

  Note:

  1. TC, by default, send the data to terminal user variables using a separate thread that executes asynchronously to the main TC thread of execution. The main thread finishes sending multiple user variables very quickly and can move on to processing the next terminal's transaction, but you can observe on a communications monitor that the data may take some time to get through the slower layers of the system and actually arrive at the terminal. Operating asynchronously to other TC processing activity with the terminal may cause sequencing problems with the transaction program running on the terminal, so a synchronous mode can be specified. Refer to the example Handling Remote Validation Request to for an example where synchronous sending mode would be desired.

  TERM_NAME	Used only with the Set_Named_Term... version, this provides the name of the target data collection terminal. The TERM_NAME is always specified as the current value of a user variable (not as a constant string).
  UV	The TC user variable.
  TERMUV* (**) (69)	The user variable number on the DCT.
  MODE	To facilitate synchronization between the TC and the terminal transaction program, the Send_Term_UV_Data command lets you specify whether the operation should be done SYNCHronously (TC blocks execution until DCConnect is finished with the transaction) or ASYNCHronously (TC uses a separate thread to send the data, not waiting in the main TC thread) for DCConnect to finish each transmission. This optional parameter can be specified as ASYNCH or SYNCH. The default mode is ASYNCH.
  ERR_LABEL	An optional label to branch to when TC encounters an error when trying to send the data to the DCT. For example, an RF terminal may have moved out of range or may have been turned off by the operator. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends. This error label only has an effect if the MODE is specified as SYNCH. ASYNCH sends that result in errors will not cause a branch/call to the ERR_LABEL. Note: TC does two retries when sending data to the DCTs. DCConnect does its own retries, there is little need to program your own retry loop unless it is absolutely required that you get the data to the terminal.

  Example:
   
    // Send user variable 1 to the current terminal's user variable 10.
    Send_Term_UV_Data( UV1, 10 )
   
    // Send user variable 25, 26, and 27 to terminal LOOM_01B user
    // variable 10-12.  Call the subroutine SUBR_FAILED_TO_SEND if the
    // data could not be sent (this subroutine may log an error report
    // into the database).
    Append_UV_Kbd_Data(UV1,"LOOM_01B")
    Send_Term_UV_Data( UV1_VALUE, 25, 10, 26, 11, 27, 12, SYNCH,
                                SUBR_FAILED_TO_SEND)
  

  Send_Term_VResp / Send_Terminal_VResp

    Send_Term_VResp( RESPONSE )
  

  Send a terminal a remote validation response. This command is valid only when TC is running in remote validation mode, refer to Transaction, Remote Validation, or Data Request Modes for additional information.

  RESPONSE

  The response you want sent to the terminal. Choices are PASS, FAIL, or UNKNOWN.

  Example:
   
    Send_Term_VResp( PASS )
  

  Send_To_Host

    Send_To_Host ( DATA_PART*, START*, LENGTH*, ROW*, COL*, CURSOR, ERROR_LABEL )
    Send_To_Host ( "String", ROW*, COL*, CURSOR, ERROR_LABEL )
    Send_To_Host ( NumericConstant, ROW*, COL*, CURSOR, ERROR_LABEL )
    Send_To_Host ( CTRL_FUNC_KEY, ERROR_LABEL )
  

  This command provides a general-use, highly flexible, and fast method to move data to the host screen. Most users prefer Send_To_Host over the legacy commands Send_Host_Kbd_Data, Send_Host_Xact_Data, and Send_Host_UV_Data. Send_To_Host is more consistent in its usage (always allowing the target row and column to be specified), and lets you control setting of the cursor position at the end of the command's execution. Also, when NONE is specified for cursor movement, Send_To_Host provides the fastest posting of data to the host screen as it does not move the cursor at all; data that does not contain control keys can be placed at the desired row and column without the need to actually move the cursor (which can take considerable time, especially when the cursor must move long distances across the screen).

  Screen_Width if your host session runs in other than 80-column mode.

  Note:

  1. Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a TC user variable by using the user variable's name or the notation UVn, where n ranges from 1 to 250 or the maximum defined by Define_UVs.

  2. Strings or data parts that contain EHLLAPI control codes (special character sequences using the @ character to represent PF keys, Enter, and so forth) will be sent in their entirety as control character sequences. This is the slowest way to send data and does not allow this function to properly position the cursor when the command is finished. Also, multiple control codes appended together in a single string may suffer from having some codes ignored by the host application. Control codes should be sent individually using this command, rather than being built up into larger user variables.

  "String"	Any desired constant text string surrounded by double-quote marks.
  NumericConstant	Numeric constants do not have to be enclosed in double quotes and can be any base 10 number, optionally having a leading negative sign and optionally having a decimal point.
  CNTL_FUNC_KEY	An identifier representing the key to be transmitted to the host session. The following are valid identifiers representing the supported keys (not case sensitive). These keys are valid for both 3270 and 5250 emulation: ENTER LEFT_TAB NEW_LINE RIGHT_TAB CLEAR CURSOR_LEFT DELETE CURSOR_RIGHT INSERT CURSOR_UP ERASE_EOF CURSOR_DOWN PRINT HOME RESET END ERASE_INPUT SYSTEM_REQUEST ATTENTION JUMP (set focus under Presentation Manager) PF1 to PF24 The following are for 5250 emulation only: PAGE_UP SPACE PAGE_DOWN HELP FIELD- FIELD_EXIT FIELD+ The following are for 3270 only: SCR_LOCK PA1 NUM_LOCK PA2 CAPS_LOCK PA3 WORD_DELETE
  DATA_PART	This specifies one of various predefined parts of the terminal transaction or other information that becomes part of the data appended to the target user variable. The predefined parts are listed in Data Parts. The data parts that are valid vary depending on whether the TC session is currently running in transaction, validation or data request mode.
  START*	The starting position within the selected data part. 0 is the beginning of the data.
  LENGTH*	The length of data to use from the data part, starting at the START position. Refer to Data Parts for the meaning of a 0 length for a given data part. It may be ignored, it may mean return no data or it may mean take all data from the START position.
  ROW*	The target row on the host screen. The top row is row 1. Set ROW and COL to 0 to copy data to the current cursor position.
  COL*	The target column on the host screen. The left-most column is column 1. Set ROW and COL to 0 to copy data to the current cursor position.
  CURSOR	Specify NONE for no cursor movement (the cursor will remain where it was when the command started); START to position the cursor at the row and column specified above, no matter how many characters are input starting at that location; or END to position the cursor in the next position past the last character of the data just sent.
  ERROR_LABEL	An optional label to branch to when TC finds that the data or control character cannot be input due to a keyboard locked condition or the host screen being busy for an extended period of time. If no label is provided, TC will log an error and terminate if a locked or busy error occurs. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends.

  Note:

  No range checking is done for row and column parameters. You must use valid values based on the size of the emulation session that is set up in CM.

  Example:
   
    // Send all of UV2 to the host screen, starting at the current
    // cursor location and leave the cursor just after the end of
    // this new data on the screen.  Do error recovery at label ERROR_1
    // if the host is locked, busy, or the data will not fit on the screen        .
    Send_To_Host ( UV2, 0, 0, 0, 0, END, ERROR_1 )
   
    // Send 10 characters from incoming transaction, starting at offset 5,
    // to row 1, column 1, without moving the cursor (for max. speed).
    // Terminate if host screen locked or busy.
    Send_To_Host ( TXNDATA, 5, 10, 1, 1, NONE )
   
    // Send 10 characters from incoming transaction, starting at offset 5,
    // to a row specified by the value of UV30, always at column 1
    Send_To_Host ( TXNDATA, 5, 10, UV30, 1, NONE, ERROR_2 )
   
    // Send an Enter key to the host
    Send_To_Host ( ENTER, LOCKED )
   
    // Send a numeric value '9' to row 6, col 53
    Send_To_Host ( 9, 6, 53, NONE )
   
    // If running in REMOTE_VALIDATION_MODE, send all of the validation
    // request data area to host row 12, column 10 (uses the special meaning
    // of Length = 0 for remote validation TXNDATA )
    Send_To_Host ( TXNDATA, 0, 0, 12, 10, NONE, ERROR_2 )
   
    // Copy all of the fifth transaction field to row 12, column 10
    Send_To_Host ( TXNFIELD5, 0, 0, 12, 10, NONE, ERROR_2 )
  

  Session

    Session ( ID )
  

  This function is used to specify the 'short name' of the PCOMM terminal emulation session to which this TC session tries to connect. This is a single character (for example: A, B and C).

  This function is an alternative to specifying the Session ID on the command line. If this command is found anywhere in the script, it overrides the command line setting.

  If the Session ID is not set from the command line or by using this command, it has the default value '*' - that is not a valid session ID to PCOMM.

  ID	A single alphabetic character from 'A' to 'Z'. It is converted to upper case before it is stored.

  Example:
   
    // Set the session ID to 'B'
    Session ( B )
  

  Session_Connect

    Session_Connect( )
    Session_Connect( PROFILE_PATH_AND_NAME )
  

  This command performs the same connection of EHLLAPI to the emulator window of this session as is done at initial start-up of TC. This is used when running in Run_Without_Session mode when attempting to establish the host session connection under script control, typically in a routine which recovers from unexpected loss of host connection.

  If a path and file name for a Personal Communications work station profile is provided with this command (or if the the Workstation_Profile / WS_Profile command has been used), the Session_Connect command will start the emulator program window if it finds that no session is already started. The profile provided in this command is used in preference to what may have been specified in the Workstation_Profile command.

  Note that this command can result in a EHLLAPI error which will be trapped by any On_Error_Goto command specifying the SESSION error, so be careful in writing scripts for session error recovery that you do not create an unintentional endless loop.

  Example:
   
    // Disconnect and re-connect Personal Communications from the host
    // and then re-connect EHLLAPI
    Communication_Disconnect( )
    Delay(3000)
    Communications_Connect()
    Delay(6000)
   
    // PComm seems to require a reconnection of EHLLAPI to the session after
    // disconnect and re-connect.
    // Replace our prior On_Error_Goto for the SESSION error with a branch
    // past this command should the command get an EHLLAPI error
    On_Error_Goto(SESSION, SessConnFail )
   
    // Specify the optional Workstation profile name so the emulator can be started
    // if not already running...
    Session_Connect( C:\PCOMOS2\PRIVATE\TN5250.WS )
   
   
    SessConnFail:
   
    // See if Session_Connect worked
    If ( SESSION_STATUS == "0" )
     {
      Log_Error("Session_Connect failed to connect HLLAPI to host session", "INFO" )
     }
  

  Set_Cursor

    Set_Cursor( ROW*, COLUMN* )
  

  This command is used to set the host screen cursor position, usually prior to sending data or keystrokes. The upper-left corner of the host display is row 1, column 1.

  See Screen_Width if your host session runs in other than 80-column mode.

  Note:

  1. No range checking is done for the row and column parameters. You must use valid values based on the size of the emulation session that is set up in Communications Manager.

  2. Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a TC user variable by using the user variable's name or the notation UVn, where n ranges from 1 to 250 or the maximum defined by Define_UVs.

  ROW*	Host screen row for cursor placement.
  COLUMN*	Host screen column for cursor placement.

  Example:
   
    // Set cursor to row 5, column 1.
    Set_Cursor( 5, 1 )
   
    // Set cursor to row and column specified in UV1 and UV2, respectively.
    Set_Cursor( UV1_VALUE, UV2_VALUE )
  

  Set_Emulator_Window

    Set_Emulator_Window( STYLE )
  

  This command is used to set the host emulator window to one of a set of Presentation Manager styles.

  STYLE

  The Presentation Manager style can be one of the following: ACTIVATE Sets focus to the window and places it in the foreground. DEACTIVATE Removes focus from the window and makes it the bottom window. MINIMIZE Minimizes the window to the desktop or minimized window viewer, as defined for your desktop. MAXIMIZE Maximizes the window on the desktop. RESTORE Restores the window size to the previous size.

  Example:
   
    // Set the emulator window to minimized.
    Set_Emulator_Window( MINIMIZED )
  

  Set_UV_Ctrl_ID

    Set_UV_Ctrl_ID ( UV )
  

  This function is the same as Append_UV_Ctrl_ID except that the target user variable is cleared before appending to it. Refer to Append_UV_Ctrl_ID for a full description of this function.

  Set_UV_Cntlr_ID

    Set_UV_Cntlr_ID ( UV )
  

  This function is the same as Append_UV_Ctrl_ID except that the target user variable is cleared before appending to it. Refer to Append_UV_Ctrl_ID for a full description of this function. This command is an alias for the Set_UV_Ctrl_ID command and provides the same function.

  Set_UV_Data_Part

    Set_UV_Data_Part ( UV, DATA_PART, START*, LENGTH* )
  

  This function is synonymous with Set_UV_Xact_Data.

  This function is the same as Append_UV_Data_Part except that the target user variable is cleared before appending to it. Refer to Append_UV_Data_Part for a full description of this function.

  Set_UV_File_Data

    Set_UV_File_Data( uvRC, uvTarget, Length*, uvDelimiter )
    Set_UV_File_Data( uvRC, uvTarget, Length* )
  

  This function is the same as Append_UV_File_Data except that the target user variable is cleared before appending to it. Refer to Append_UV_File_Data for a full description of this function.

  Set_UV_Host_Data

    Set_UV_Host_Data ( UV, ROW*, COL*, LENGTH* )
  

  This function is the same as Append_UV_Host_Data except that the target user variable is cleared before appending to it. Refer to Append_UV_Host_Data for a full description of this function.

  Set_UV_Kbd_Data / Set

    Set_UV_Kbd_Data ( UV, "String" )
    Set_UV_Kbd_Data ( UV, CTRL_CODE )
    Set_UV_Kbd_Data ( UV, %EnvironmentVariable% )
  
    Set ( UV, "String" )
    Set ( UV, CTRL_CODE )
    Set ( UV, %EnvironmentVariable% )
  

  This function is the same as Append_UV_Kbd_Data / Append except that the target user variable is cleared before appending to it. Refer to Append_UV_Kbd_Data / Append for a full description of this function.

  Set was added as a synonym for Set_UV_Kbd_Data in version 3.1.0e.

  Set_UV_Select_Data / Set_UV_Select_Data2

    Set_UV_Select_Data ( UV, SELECT_ITEM, ERR_LABEL )
    Set_UV_Select_Data ( UV, SELECT_ITEM, ERR_LABEL, FORMAT )
    Set_UV_Select_Data2 ( DataSourceAlias*, UV, SELECT_ITEM, ERR_LABEL, ... )
  

  This function is the same as Append_UV_Select_Data except that the target user variable is cleared before appending to it. Refer to Append_UV_Select_Data for a full description of this function.

  Set_UV_Seq_Num

    Set_UV_Seq_Num ( UV )
  

  This function is the same as Append_UV_Seq_Num except that the target user variable is cleared before appending to it. Refer to Append_UV_Seq_Num for a full description of this function.

  Set_UV_UV

    Set_UV_UV ( TARGET_UV, SOURCE_UV, START*, LENGTH* )
  

  This function is the same as Append_UV_UV except that the target user variable is cleared before appending to it. Refer to Append_UV_UV for a full description of this function.

  Set_UV_Xact_Data

    Set_UV_Xact_Data ( UV, DATA_PART, START*, LENGTH* )
  

  This function is an alias for Set_UV_Data_Part. Refer to Set_UV_Data_Part for a full description of this function.

  Set_Xact_Time_Of_Origin

    Set_Xact_Time_Of_Origin( DATAPART, START*, LENGTH* )
  

  This command is called to set the date and time for the current transaction. The transaction date and time is initially set when it is created at its source. This command allows you to override that initial value. You might need to do this if the transaction originated in a different time zone.

  Changing the transaction date and time affects the Xact_Age command and it affects what is returned for the following data parts:

  • TIMESTAMP

  • TIMESTAMP4

  • DATE

  • DATE4

  • YEAR

  • YEAR4

  • MONTH

  • DAY

  • HOUR

  • MINUTE

  • SECOND

  • XACT_AGE

  There are three options for the format of the date/time string that is accepted by this command:

  1. YYMMDDHHmmss

  2. YYYYMMDDHHmmSS

  3. YYYY?MM?DD?HH?mm?SS

  In the last format, the question marks indicate that any separator can go between the various date and time values; TC just pulls the date and time values from the indicated positions.

  DATA_PART	This specifies one of various predefined parts of the terminal transaction or other data part that will contain the date and time string. The predefined parts for this parameter are shown in Data Parts. The data parts that are valid vary depending on whether the TC session is currently running in transaction, validation or data request mode.
  START*	The starting position within the data part at which to find the date and time string. Zero is the beginning of the data.
  LENGTH*	The length of data to use from the data part, starting at the START position. Refer to Data Parts for the meaning of a 0 length for a given data part. It may be ignored, it may mean return no data or it may mean take all data from the START position.

  Example:
   
    // Get the current transaction time stamp
    Set_UV_Xact_Data(UV1, TIMESTAMP, 0, 0)
   
    // ... Adjust timestamp based on difference in time zone (e.g. +1 hour)
    // ... so that it is appropriate for the DCConnect Server
   
    // Then update the transaction time
    Set_Xact_Time_Of_Origin(UV1)
   
    // Now Xact_Age can be used to accurately check the age of the transaction
    Xact_Age( Do_not_bother, 45 )
   
    // ...
    // Process transaction here
    // ...
   
  Do_not_bother:
   
  

  Setup_Insert_Field

    Setup_Insert_Field( COLUMN, COL_TYPE, DATA_PART, START, LENGTH )
    Setup_Insert_Field( COLUMN, COL_TYPE, DATA_PART, START, LENGTH,
                              PREFIX )
    Setup_Insert_Field( COLUMN, COL_TYPE, DATA_PART, START, LENGTH,
                              PREFIX, SUFFIX )
  

  This is the second command in the series used to INSERT a row (record) into a database table. It specifies which column of the table is to be affected and what data should be assigned to the column for this new row. This command can be repeated up to 255 times, once for each possible column allowed in a table between the Insert_DB_Table and Perform_Insert commands.

  For additional information refer to Insert_DB_Table and Perform_Insert.

  COLUMN	The table column name.
  COL_TYPE	The type of data stored in the column: NUMERIC, CHARACTER, TIME, DATE, or TIMESTAMP. The type tells TC whether to put quotes around the data (CHARACTER or time/date types) and whether to add delimiters and the century to time/date types. For time/date types, the input data can be in the form sent by the terminal or it can already have delimiters in place. Data for a TIME type column must be in the form HHMMSS (as it comes from the terminal), HH:MM:SS, or 'HH:MM:SS'. Data for a DATE type column must be in the form YYMMDD (as it comes from the terminal), YYYY/MM/DD, or 'YYYY/MM/DD'. Data for a TIMESTAMP type column must be in the form YYMMDDHHMMSS (as it comes from the terminal), YYYY-MM-DD-HH.MM.SS, or 'YYYY-MM-DD-HH.MM.SS'.
  DATA_PART	This specifies one of various predefined parts of the terminal transaction or other information that becomes part of the data inserted into this column of the row. The predefined parts listed in Data Parts. The data parts that are valid vary depending on whether the TC session is currently running in transaction, validation or data request mode. If the datapart is empty (typically a user variable or transaction field) it will be put into the SQL string as an empty string ('') for CHARACTER columns or as NULL for any other type of column.
  START	The starting position within the specified data part. 0 is the beginning of the data.
  LENGTH	The length of data to use from the data part, starting at the START position. Refer to Data Parts for the meaning of a 0 length for a given data part. It may be ignored, it may mean return no data or it may mean take all data from the START position.
  PREFIX	An optional string to append as a prefix to the data from the DATA_PART. The data used for the command is formulated by appending the three elements: PREFIX+DATA_PART+SUFFIX For example, to insert a constant initial quantity of 0.0 to a numeric field in a new row, specify the DATA_PART as NULL and the PREFIX as 0.0 (no quote marks). If you do not want a prefix but do want a suffix, specify the PREFIX to be NULL. You cannot have a suffix without a prefix as a place holder in the command.
  SUFFIX	An optional string to append as a suffix to the data from the DATA_PART. The data used for the command is formulated by appending the three elements: PREFIX+DATA_PART+SUFFIX You can specify the SUFFIX as NULL, which is equivalent to not specifying a SUFFIX at all and simply ending the command string with the ending ')'.

  Examples:
   
    // Set BADGE to first 7 characters of transaction data.
    Setup_Insert_Field( BADGE, CHARACTER, TXNDATA, 0, 7)
   
    // Set QUANTITY to 0.0 (constant) using the PREFIX parameter.
    Setup_Insert_Field( QUANTITY  , NUMERIC, NULL, 0, 0, 0.0 )
   
    // Set QUANTITY to NULL using an empty user variable.
    Clear_UV( UV1 )
    Setup_Insert_Field( QUANTITY  , NUMERIC, UV1, 0, 0 )
  

  Setup_Update_Field

    Setup_Update_Field( COLUMN, COL_TYPE, DATA_PART, START, LENGTH )
    Setup_Update_Field( COLUMN, COL_TYPE, DATA_PART, START, LENGTH,
                              PREFIX )
    Setup_Update_Field( COLUMN, COL_TYPE, DATA_PART, START, LENGTH,
                              PREFIX, SUFFIX )
  

  This is the second command in the series used to UPDATE a row (record) of a database table. It specifies which column of the table is to be affected and what data should be assigned to or used to modify (add, subtract, and so forth) the column for the row or rows that meet the WHERE criteria. This command can be repeated up to 255 times (once for each possible column allowed in a table) between the Update_DB_Table and Update_Where commands.

  See also Update_DB_Table, Update_Where, Perform_Update, and the example Updating a Record in a Table.

  COLUMN	The table column name
  COL_TYPE	The type of data stored in the column: NUMERIC, CHARACTER, TIME, DATE, or TIMESTAMP. The type tells TC whether to put quotes around the data (CHARACTER or time/date types) and whether to add delimiters and the century to time/date types. For time/date types, the input data can be in the form sent by the terminal or it can already have delimiters in place. Data for a TIME type column must be in the form HHMMSS (as it comes from the terminal), HH:MM:SS, or 'HH:MM:SS'. Data for a DATE type column must be in the form YYMMDD (as it comes from the terminal), YYYY/MM/DD, or 'YYYY/MM/DD'. Data for a TIMESTAMP type column must be in the form YYMMDDHHMMSS (as it comes from the terminal), YYYY-MM-DD-HH.MM.SS, or 'YYYY-MM-DD-HH.MM.SS'.
  DATA_PART	This specifies one of various predefined parts of the terminal transaction or other information that becomes part of the data updated in this column of the row. The predefined parts are shown for this parameter in Data Parts. The data parts that are valid vary depending on whether the TC session is currently running in transaction, validation or data request mode. If the datapart is empty (typically a user variable or transaction field) it will be put into the SQL string as an empty string ('') for CHARACTER columns or as NULL for any other type of column.
  START	The starting position within the specified data part. 0 is the beginning of the data.
  LENGTH	The length of data to use from the data part, starting at the START position. Refer to Data Parts for the meaning of a 0 length for a given data part. It may be ignored, it may mean return no data or it may mean take all data from the START position.
  PREFIX	An optional string to append as a prefix to the data from the DATA_PART. The data used for the command is formulated by appending the three elements: PREFIX+DATA_PART+SUFFIX For example, to add a number from the transaction to the current value in the QUANTITY column, specify the DATA_PART as TXNDATA or TXNFIELDn, and set the PREFIX to QUANTITY+. If you do not want a prefix but do want a suffix, specify the PREFIX to be NULL. You cannot have a suffix without a prefix as a place holder in the command.
  SUFFIX	An optional string to append as a suffix to the data from the DATA_PART. The data used for the command is formulated by appending the three elements: PREFIX+DATA_PART+SUFFIX You can specify the SUFFIX as NULL, which is equivalent to not specifying a SUFFIX at all and simply ending the command string with the ending ')'.

  Example:
   
    // Set BADGE to first 7 characters of transaction data.
    Setup_Update_Field( BADGE, CHARACTER, TXNDATA, 0, 7)
   
    // Set QUANTITY to 0.0 (constant) using the PREFIX parameter.
    Setup_Update_Field( QUANTITY  , NUMERIC, NULL, 0, 0, 0.0 )
  

  Show_Thread_Messages

    Show_Thread_Messages
  

  As of 05-13-05, the default behavior of TC is to no longer show any messages about the starting and stopping of threads. This was done because sometimes customers would question whether or not those messages should be something to worry about.

  To override this default behavior, include this new keyword in the script file.

  Example:
   
    Show_Thread_Messages
  

  Silent

    Silent
  

  This command is used to turn off the warning beeps produced by TC whenever an informational or error message is posted to the display. If the Silent command is included anywhere in the command script file, TC will run with the speaker turned off.

  Example:
   
    Silent
  

  Shutdown_DCConnect

    Shutdown_DCConnect ( ABSOLUTE_NO | ABSOLUTE_YES )
    Shutdown_DCConnect ( ABSOLUTE_NO | ABSOLUTE_YES, OPT_ERR_LABEL )
  

  Shut down the DCConnect Server. The first parameter indicates whether the shut down should be done regardles of whether any terminals are downloading (ABSOLUTE_YES) or if the shut down request should be ignored if any terminals are currently downloading (ABSOLUTE_NO).

  ABSOLUTE_NO	The shutdown request should be ignored if any terminals are currently being downloaded by the DCConnect Server.
  ABSOLUTE_YES	The shutdown request should be honored even if there are any terminals that are currently being downloaded by the DCConnect Server.
  OPT_ERR_LABEL	If an error label is provided, control will branch to this label if an error occurs when trying to shut down the DCConnect Server (e.g. the DCConnect Server is not running). The data part LAST_ERROR will contain the error code. If the label name is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends. The label is optional; if not specified, the script will always execute the next command step - unless the error causes TC to terminate.

  Example:
   
    // Shut down the DCConnect Server even if terminals are being downloaded
    Shutdown_DCConnect( ABSOLUTE_YES )
  
  

  SQL_Buffer_Size

    SQL_Buffer_Size ( NEWSIZE )
  

  This command is used to increase the size of the buffer used for building SQL commands. The default size is 4000 bytes.

  This command can be used to avoid getting the following message:

   
    XIS103:The SQL statement is too long to fit in internal buffers
   
  

  NEWSIZE

  Pick a numeric value greater than 4000 bytes for the new size.

  Example:
   
    SQL_Buffer_Size(10000)
   
  

  Start_Application

    Start_Application ( APPLICATION_NAME* )
    Start_Application ( APPLICATION_NAME*, OPT_ERR_LABEL )
  

  Start the specified application - which must be part of the DCConnect configuration.

  Note: Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a TC user variable by using the user variable's name or the notation UVn, where n ranges from one to 250 or the maximum defined by Define_UVs.

  APPLICATION_NAME*

  The name of the application to be started. This must be defined in the DCConnect configuration. This name is case-sensitive. If not using a user variable for the application name, it must be enclosed in double quotes.

  OPT_ERR_LABEL

  If an error label is provided, control will branch to this label if an error occurs when trying to start the application (e.g. the DCConnect Server is not running). The data part LAST_ERROR will contain the error code. If the label name is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends. The label is optional; if not specified, the script will always execute the next command step - unless the error causes TC to terminate.

  Examples:
   
    ...
    Declare( uvApplication )
    ...
   
    // Start the application with the name Cleanup_Logs
    Start_Application( "Cleanup_Logs" )
  
    // Start the same application but get the name from a user variable and branch to an error label if the operation fails
    Set_UV_Kbd_Data( uvApplication, "Cleanup_Logs")
    Start_Application( uvApplication, StartFailed)
  
    Goto ( StartSucceeded )
  
  StartFailed:
    // Handle failure
  
  StartSucceeded:
    // Handle success
   
  

  StartFunctionGroup / StartCluster

    StartFunctionGroup ( NAME )
    StartCluster ( NAME )
  

  This command used to tell TC which set of processing commands (script) should be executed for an incoming transaction. Two identifying features of the incoming data transaction are used to determine how the data is to be processed: the originating function group of terminals (if this optional command is used) and the event on the individual terminal used to initiate the transaction program. This command specifies the DCConnect function group (logical group of terminals that all act alike) to which all of the following StartKey / EndKey groups belong (up until the next EndFunctionGroup / EndCluster).

  This command is optional in the command file. The originating function group of each incoming transaction is checked to see if the function group name matches any function group name specified in a StartFunctionGroup command. If the function group names match, the set of StartKey scripts for the function group is searched for a match against the ID of the transaction. If a match is found, that script is executed.

  Any StartKey scripts defined outside the limits of a StartFunctionGroup / EndFunctionGroup set become part of the default function group. An incoming transaction whose originating function group does not match any defined function group is processed using this default function group of StartKey scripts.

  When there are no StartFunctionGroup / EndFunctionGroup groups, you cannot have duplicate event IDs in the StartKey / EndKey key scripts, as this would be ambiguous as to which should be used. Within a function group (or within the entire set of script command files, if StartFunctionGroup is not used), you can use as many StartKey commands as you like, as long as the EVENT_ID is not duplicated.

  This command is valid only when processing transactions; it is not valid when processing validation requests or data requests.

  StartFunctionGroup is always used in conjunction with EndFunctionGroup / EndCluster, that terminates the set of StartKey scripts.

  NAME	The exact DCConnect function group by which to sort processing of incoming transactions.

  Example:
   
    StartFunctionGroup( MFG_ASSEMB_1 )
  

  StartInterval

    StartInterval( INTERVAL )
  

  This command is used to indicate the start of the script to be executed at the time intervals specified in the parameters. If another script is being executed when the interval expires, the StartInterval command will be queued for execution as soon the other script is completed (and after any queued StartTime scripts have been executed).

  There can be only one StartInterval / EndInterval set in a script.

  This command is useful for tasks such as periodically checking to see if the database connection is still up. It begins the script to be run; while EndInterval is used to end the script.

  Note:

  While executing, the next scheduled execution time based on the StartTime command is shown on the TC screen after the text Next Time:.

  INTERVAL

  The interval in milliseconds between executions of the script. The range of milliseconds is 1 to 4,294,967,295 (.001 seconds to 49.7 days).

  Example:
   
    // This script allowed to run without a DB connection.
    Run_Without_Connect
   
    // Check once a minute for active DB connection.
    // 60 seconds is 60*1000 = 60000 milliseconds.
    StartInterval( 60000 )
   
      // For DB2, a -1024 error results when trying
      // select without DB connection.
      On_Error_Goto( -1024, DB_IS_DOWN )
   
      // Put SQL Select statement here.
   
      Goto END_INTERVAL
   
    DB_IS_DOWN:
   
      // Show error message (causes beep to sound also).
      Log_Error( "DB is down!!" )
      Log_Error( "DB is down!!" )
      Log_Error( "DB is down!!" )
   
    END_INTERVAL:
   
    EndInterval()
  

  StartKey

    StartKey ( EVENT_ID )
  

  This command is used to tell TC which set of processing commands (script) should be executed for an incoming transaction. Two identifying features of the incoming data transaction are used to determine how the data is to be processed: the originating function group of terminals (if the optional StartFunctionGroup / StartCluster command is used) and the event on the individual terminal used to initiate the transaction program. This command specifies the initial event to which the command steps apply.

  This command is valid when only processing transactions; it is not valid when processing validation requests or data requests.

  Within a function groups or within the entire script command file, if StartFunctionGroup / StartCluster is not used, you can use as many StartKey commands as you like, as long as the EVENT_ID is not duplicated.

  StartKey is always used in conjunction with EndKey, which terminates the set of command steps.

  See also the command StartMatch for a method to run a script based on the character content of some portion of the transaction or other TC data part.

  EVENT_ID

  The transaction identification that came from the terminal, identifying which terminal event was used to initiate the transaction. Choices include: Function Keys: "F1", "F2", "F3", "F4", "F5", "F6", "F7", "F8", "F9", "F10", "F11", "F12", "F13", "F14", "F15", "F16", "F17", "F18", "F19", "F20", "F21", "F22", "F23", "F24", "F25", "F26", "F27", "F28", Badge-initiated or Fast-Clocking: "BADGE", "CLOCKING", Programmable Function Keys: "PF1", "PF2", "PF3", "PF4", "PF5", "PF6", "PF7", "PF8", "PF9", "PF10", "PF11", "PF12", "SHIFT_PF1", "SHIFT_PF2", "SHIFT_PF3", "SHIFT_PF4", "SHIFT_PF5", "SHIFT_PF6", "SHIFT_PF7", "SHIFT_PF8", "SHIFT_PF9", "SHIFT_PF10", "SHIFT_PF11", "SHIFT_PF12", General-Purpose Serial Port: "GP1", Digital Input Points: "DI0", "DI1", "DI2", "DI3", "DI4", "DI5", "DI6", "DI7", Touch Screen Regions: "RGN1", "RGN2", "RGN3", "RGN4", "RGN5", "RGN6", "RGN7", "RGN8", "RGN9", "RGN10", "RGN11", "RGN12", "RGN13", "RGN14", "RGN15", "RGN16", "RGN17", "RGN18", "RGN19", "RGN20", "RGN21", "RGN22", "RGN23", "RGN24", "RGN25", "RGN26", "RGN27", "RGN28", "RGN29", "RGN30", "RGN31", "RGN32", "RGN33", "RGN34", "RGN35", "RGN36", "RGN37", "RGN38", "RGN39", "RGN40", Additional Events: "ADDL1", "ADDL2", "ADDL3", "ADDL4", "ADDL5", "ADDL6", "ADDL7", "ADDL8", Time-of-Day: "TOD"

  Example:
   
    StartKey( F1 )
  

  StartLogoff

    StartLogoff ( )
  

  This command is used to indicate the start of the Logoff script to be executed each time TC ends. The StartLogoff command begins the script, while EndLogoff is used to end the script.

  Example:
   
    StartLogoff()
      Send_Host_Kbd_Data( PF12 )
      Send_Host_Kbd_Data( PF12 )
      Send_Host_Kbd_Data( PF12 )
      Set_Cursor( 24,7 ) // Command line
      Send_Host_Kbd_Data("Logoff")
      Send_Host_Kbd_Data( ENTER )
    EndLogoff( )
  

  StartLogon

    StartLogon ( )
  

  This command is used to indicate the start of the Logon script to be executed each time TC starts. The StartLogon command begins the script, while EndLogon is used to end the procedure.

  Example:
   
    StartLogon()
      Set_Cursor( 5,43 ) // User ID input field
      Send_Host_Kbd_Data("JUNEC")
      Set_Cursor( 6,43 ) // Password input field
      Send_Host_Kbd_Data("J5J5J5J")
      Send_Host_Kbd_Data( ENTER )
    EndLogon( )
  

  StartMatch

    StartMatch( "string", DATA_PART, START, LENGTH)
  

  The StartMatch command is an alternative to StartKey, StartCluster and StartVal for indicating which script should be executed against an incoming transaction (from DCConnect or a defined interface). StartMatch allows a piece of the incoming transaction or remote validation data itself to determine which definition is used, rather than using the function group name and transaction ID (key event ID) or the remote validation file name. For example, you could look at the first three characters of the transaction data to determine which script is used.

  When a transaction is received, any matches to StartMatch data are evaluated first. If a match is found, that script is executed. If no match is found, the regular function group/key ID or remote validation file name search is performed.

  As of 3/23/2005 you can have over 6000 StartMatch scripts and subroutines combined. (Prior to this, up to 125 StartMatch scripts were allowed for each TC session).

  "string"	The string of characters that must match the piece of data defined in the following parameters.
  DATA_PART	This specifies one of various predefined parts of the terminal transaction or other information that is used to match against the string defined above. The predefined data parts listed in Data Parts. The data parts that are valid vary depending on whether the TC session is currently running in transaction, validation or data request mode.
  START	The starting position within the specified data part. 0 is the beginning of the data.
  LENGTH	The length of data to use from the data part, starting at the START position. Refer to Data Parts for the meaning of a 0 length for a given data part. It may be ignored, it may mean return no data or it may mean take all data from the START position.

  Example:
   
    // Run this script if the first 3 characters
    // of the data are "010".
    StartMatch ( "010", TXNDATA, 0, 3 )
   
    // Do remote validation based on terminal name instead of
    // validation file name.
    StartVal( BADGES.VAL )
      // Empty set used to 'register' the validation file name.
    EndVal()
   
    StartMatch( "Front_Entrance_03A", TERMINALNAME, 19)
      // Do work.
    EndMatch()
  

  StartSubroutine

    StartSubroutine( SUB_NAME )
  

  This command starts the definition of a subroutine script. A subroutine script has the same structure as a StartKey/ EndKey script, but it uses your arbitrary subroutine name instead of an event ID. Inside the subroutine, you can use the same commands that can be used in a StartKey/StartMatch/... script.

  When the commands in a subroutine are all executed, control returns to the script which called the subroutine, at the command which follows the call to the subroutine. The subroutine can include the Return() command to end the subroutine before the last command in the subroutine script is encountered.

  As of 3/23/2005 you can have over 6000 subroutines and StartMatch scripts combined. (Earlier limits were 250 (fix packs D-F for version 1.40) and 125 (prior to fix pack D for version 1.40)). The subroutine script is completed with the command EndSub / EndSubroutine and is called with the command Call_Subroutine.

  SUB_NAME

  The name you want to give to your subroutine. It can be up to 32 characters in length, and must be unique among all subroutines and labels used in the command file.

  Example:
   
    StartSubroutine( Set_Update_On_Error_Group )
  

  StartTime

    StartTime( HH:MM:SS )
  

  This command is used to indicate the start of a script to be executed at the time specified in the parameters. You can specify up to 124 different time-of-day-initiated scripts to be executed throughout the day.

  If another script is being executed when a time-of-day event occurs for one of the defined StartTime scripts, the StartTime script will be queued for immediate execution as soon as the first currently running script is completed.

  Note:

  While executing, the next scheduled execution time based on the StartTime command is shown on the TC screen after the text Next Time:.

  This command is useful for tasks such as preparing a report from the database at a certain time each day, causing a logoff from the host during scheduled down-times, and so forth.

  The StartTime command begins the definition of the script, while EndTime is used to end the script.

  HH:MM:SS

  The time, specified in military format, at which you want the script to be executed.

  Example:
   
    // Prepare a report at 3 a.m. each day.
    StartTime( 03:00:00 )
   
      // Put SQL Select statement here
      // and use Log_Data to create report file.
   
    EndTime()
  

  StartTimeout

    StartTimeout()
  

  This command is used to indicate the start of the Timeout script to be executed each time TC times out while waiting for a transaction from DCConnect. The timeout value is set using the command Max_Xact_Wait. See Multiple DCT Transactions to a Host Screen for an example of how this command can be used.

  This command is useful for tasks such as shutting down TC when no transactions are available for processing.

  The StartTimeout command begins the definition of the script, while EndTimeout is used to end the script.

  Example:
   
    // A manual procedure or a COMMAND file has dialed a modem
    // to connect to headquarters, and a switched line PCOMM remote
    // database connection has been started.  As soon as all accumulated
    // DCT transactions have been transferred to the server system,
    // we want to terminate the TC session, which
    // will allow the phone line to be dropped.
   
    // If no transactions are available for 2 seconds, call
    // the TIMEOUT procedure.  2 seconds is plenty of time
    // for DCConnect to retrieve any available transactions.
    Max_Xact_Wait ( 2000 )
   
    StartTimeout()
   
      Log_Error ( "Transactions completed, logging off...")
   
      End_TC()
   
    EndTimeout()
  

  StartVal

    StartVal ( NAME.VAL )
  

  This command is used to tell TC which set of processing commands (script) should be executed for an incoming remote validation request.

  This command is valid only when processing validation requests; it is not vald when processing transactions or data requests. For additional information, refer to Transaction, Remote Validation, or Data Request Modes.

  You can use as many as 125 StartVal commands in a command file, as long as the NAME.VAL file names are not duplicated.

  StartVal is always used in conjunction with EndVal, that terminates the set of command steps.

  NAME.VAL

  The remote validation file the terminal transaction program requests. This must be in ALL CAPITALS and include the file extension VAL.

  Example:
   
    StartVal( BADGES.VAL )
  

  Start_WS / StartWebService

    Start_WS( "ServiceName", GlobalUV )
  

  This command marks the section of the script (scriptlet) that will handle a specific incoming request for a web service.

  "ServiceName"	Constant string literal that matches the incoming web service request's name. The web service request must be to [service name].tcws -- such as to http://myserver/[servicename].tcws
  GlobalUV	A TC global user variable that will be automatically filled upon invocation with the handle of the incoming request XML. This may be a standard name such as UV1, or a named variable.

  Example:
  
  Name_UV( UV1, gHandle ) 
  
  // Processing Scriptlet for "ShowOrder" web service
  Start_WS ("ShowOrder", gHandle)
  
     Declare (varA)
     Declare (varB)
     Declare (outHandle)
     Declare (rc)
     Declare ( OrderID )
     Declare ( OrderDate )
     
     WS_EnterElement(gHandle,"soap:Body", 1, rc)
     
     WS_EnterElement(gHandle,"tns:ShowOrder", 1, rc)
  
     WS_GetElement (gHandle, "tns:orderID", OrderID, rc)
     
     // Create a response to the received request.
     // The web service table indicates that the response is
     // in SOAP XML format, so this automatically creates the soap:Envelope
     // as the root element and creates empty soap:Header and soap:Body
     // elements as children.
     WS_CreateResponse (gHandle, outHandle)
  
     // Navigate into soap:Body element 
     WS_EnterElement ( outHandle, "soap:Body", 1, rc )
     
     // Create a child under soap:Body
     WS_CreateElement(outHandle,"tns:ShowOrderResponse", rc)
     WS_EnterElement( outHandle, "tns:ShowOrderResponse", rc )
     
     WS_SetElement( outHandle, "tns:Result", 1, "OK", rc ) 
     
     // Send the response message
     WS_SendResponse( outHandle )
     
     WS_Cleanup( gHandle )
     WS_Cleanup( outHandle ) 
   
  

  Sub

    Sub SUB_NAME ( parm1, parm2, ..., parmN  )
  

  This command defines a subroutine with optional calling parameters. As of 3/23/2005 you can have over 6000 subroutines and StartMatch scripts combined. (Earlier limits were 250 (fix packs D-F for version 1.40) and 125 (prior to fix pack D for version 1.40)).

  The subroutine script is enclosed between a Sub command and EndSub / EndSubroutine command, and is called using the Call command.

  SUB_NAME

  The name of the subroutine being defined

  parm1, ..., parmN

  The local names of the parameters passed to the subroutine. From the calling script the parameters may be any combination of global user variables, local user variables, or constant strings. Inside the subroutine they are referered to by the names given in the Sub parameter list. User variables are passed by address (reference) so the called routine may change them before returning. Temporary storage is created for constant strings and the address of this storage is passed to the routine (which may then change what is in the storage, but the calling script will never be able to see what the new value was). The number of parameters passed must match the number defined in the Sub command.

  Example:
   
    Name_UV( UV1, gUserID )
    StartMatch( "MOVE", TXNFIELD1, 0, 4 )
   
      Declare( ItemNumber )
      Declare( Short_Item )
   
      Set_UV_Xact_Data( gUserID,    TXNFIELD2, 0, 0 ) // User from txn
      Set_UV_Xact_Data( ItemNumber, TXNFIELD3, 0, 0 ) // Item fromtxn
   
      // Ask my utility routine to convert input item to
      // the ERP system's short_item number and return it
      // in Short_Item
      Call ConvertItem( gUserID, ItemNumber, "CNV_SHORT", Short_Item  )
   
       ...
    EndMatch()
   
    Sub ConvertItem( InUserID, InItem, InMode, OutItem )
   
      Declare( TempItem )
   
      ... logic to check conversion mode desired (InMode) and
          do conversion...
   
      Set_UV_UV( OutItem,  TempItem )
   
      // Note that a TC trace log will show that changing the value
      // of OutItem affected the named user variable Short_Item at the
      // higher level:
      // " Short_Item<-OutItem (4): 7589 "
   
    EndSub()
  

  Submit_Client_Files

    Submit_Client_Files ( TargetType, TargetName, ClientFilesListPath, SubmitMode )
    Submit_Client_Files ( TargetType, TargetName, ClientFilesListPath, SubmitMode, ErrorLabel )
  

  Submits one or more DCConnect Client files to be loaded to a single terminal, all terminals of a certain model or all terminals in a specific function group. The files to be submitted would typically be either a new set of Client executables (etspt.exe, etspt.dll and etsscrpt.dll) and/or an updated EMULATOR.INI.

  For more details about the format of the Client Files List file and other information, see the DcxSubmitClientFiles API in the DCConnect Technical Reference.

  Note that the only errors that could occur with this command would be if the parameters are invalid, files are not found or the DCConnect Server is not running. If the load is to be done now, it will be treated the same way as when using the return WHEN_QUEUED option for the Load_Terminal command; the server will continue to retry the download if any errors occur during attempts to download the client files.

  Note also that this command can only be used to load new client files to terminals running version 3.1.0 or later of the DCConnect Client.

  TargetType	Must be one of TERMINAL, MODEL or FUNCTION_GROUP to indicate what the TargetName in the second parameter represents.
  TargetName	Indicates the specific terminal, or terminal model or function group of terminals for which the client files are being submitted.
  ClientFilesListPath	Full path to the file that lists the client file(s) that are to be submitted. This path may contain one or more environment variables which are denoted by their starting and ending percent signs (%). TC will resolve these environment variables at compile time. For each file being submitted, the client list file should contain an entry with a format similar to the following: [FILE] NAME_ON_CLIENT = etspt.exe.new PATH_ON_SERVER = c:\dcconn\dcclient\fixes\win32\etspt.exe The file must exist on the server as specified by the PATH_ON_SERVER.
  SubmitMode	Must be one of STAGE_ONLY or STAGE_AND_LOAD to indicate if the files should just be staged by the DCConnect Server for now (to be loaded to the terminals at a later time) or if they should be submitted and loaded now.
  ErrorLabel	The default label to branch to in the event of an error. If the label is the name of a subroutine, the subroutine is called instead of a Goto being used, and control returns to the next command when the subroutine ends. The label is optional; if not specified, the script always execute the next command step.

  Examples:
   
    // Submit a list of Client files to be updated on all model WIN32 terminals.  The files should
    // be staged and loaded right away.  Don't use the error label; instead check the LAST_ERROR
    // data part to see if an error occurred.
    Submit_Client_Files( MODEL, WIN32, c:\updates\dcclient\win32\ClientFiles.lst, STAGE_AND_LOAD )
    If (Last_Error != 0)
    {
       // Handle error
    }
   
    // Submit a list of Client files to the terminal named Back_Door, but don't load it right now, just
    // stage it.  Load_Terminal will be used to initiate the download of these files during off peak 
    // hours.  Here an error label will be branched to if an error occurs.
    Submit_Client_Files( TERMINAL, Back_Door, c:\updates\dcclient\cv60\ClientFiles.lst, STAGE_ONLY, SUBMIT_FAILED )
    
    // Success logic
  
  SUBMIT_FAILED:
  
    // Error logic
  
  
  

  Submit_Validation

    Submit_Validation ( SOURCE, TARGET )
    Submit_Validation ( SOURCE, TARGET, DONT_LOAD )
  

  Submit a text file to DCConnect for conversion to a validation file. DCConnect automatically downloads the file to all terminals that use this file.

  Rules for the format of the source text file are provided in the DCConnect Technical Reference.

  Refer to Creating a Badge File at 4:00 a.m. for an example that automatically creates a validation file of employee badges each morning at 4 a.m..

  SOURCE	The source text file containing the data to be submitted. Include the full path to the file if it is not located in the DCCONN/VAL directory. This file can have any file extension except VAL. The filename may contain one or more environment variables which are denoted by their starting and ending percent signs (%). TC will resolve these environment variables at compile time.
  TARGET	The name of the target DCConnect .VAL file. This must be specified in all uppercase, and must use the.VAL extension.
  DONT_LOAD	This optional third parameter tells TC to tell the DCConnect Server that this file should only be recreated; it should not be loaded to any terminal.

  Examples:
   
    // Submit a text file and have it loaded to all terminals that require it
    Submit_Validation( C:\DATA\BADGES.DAT, BADGES.VAL )
   
    // Submit a text file but do not download it to any terminal at this time
    Submit_Validation( C:\DATA\BADGES.DAT, BADGES.VAL, DONT_LOAD )
  

  Sync_Date_Time

    Sync_Date_Time ( SET_DATETIME | SYNC_DATETIME, YEAR_UV, MONTH_UV, DAY_UV, HOUR_UV, MINUTE_UV, SECOND_UV)
    Sync_Date_Time ( SET_DATETIME | SYNC_DATETIME, YEAR_UV, MONTH_UV, DAY_UV, HOUR_UV, MINUTE_UV, SECOND_UV, OPT_ERR_LABEL)
    Sync_Date_Time ( SYNC_TERMINALS )
    Sync_Date_Time ( SYNC_TERMINALS, OPT_ERR_LABEL)
  

  This command sets the date and time of the DCConnect Server system and/or updates the terminals from the DCConnect Server. If both functions are to be performed, the system date and time are set before updating the terminals.

  Note: Terminals of the DWTS type in DCConnect are not affected by this command.

  When the SYNC_TERMINALS option is specified for the first parameter the six date and time parameters should not be included because the date and time of the DCConnect Server are not updated by this option; it just updates the terminals from the current date and time of the DCConnect Server system.

  The optional label can be used to direct control of the script to an error label or error subroutine if the DCConnect Server returns an error when attempting to execute this command. If no error label is specified, control continues with the next command regardless of whether there is an error. In either case the data part LAST_ERROR will be set to the error code - which will be one of the DCConnect API return codes (see the DCConnect Technical Reference for the meanings of return codes).

  SET_DATETIME	When this keyword is used for the first parameter the date and time parameters must also be provided and the command will update the date and time on the DCConnect Server system. It will not cause the DCConnect Server to synchronize the new date and time with the terminals.
  SYNC_DATETIME	When this keyword is used for the first parameter the date and time parameters must also be provided and the command will update the date and time on the DCConnect Server system and then it will cause the DCConnect Server to synchronize the new date and time with the terminals.
  SYNC_TERMINALS	When this keyword is used for the first parameter the date and time parameters should not be provided. The command will cause the DCConnect Server to synchronize the terminals with the current date and time of the DCConnect Server. time with the terminals.
  YEAR_UV	Must contain 4 digit year to be used when the first parameter is either SET_DATETIME or SYNC_DATETIME.
  MONTH_UV	Must contain the numeric month (1-12) to be used when the first parameter is either SET_DATETIME or SYNC_DATETIME.
  DAY_UV	Must contain the numeric day (1-31) to be used when the first parameter is either SET_DATETIME or SYNC_DATETIME.
  HOUR_UV	Must contain the hour (0-23) to be used when the first parameter is either SET_DATETIME or SYNC_DATETIME.
  MINUTE_UV	Must contain the minute (0-59) to be used when the first parameter is either SET_DATETIME or SYNC_DATETIME.
  SECOND_UV	Must contain the second (0-59) to be used when the first parameter is either SET_DATETIME or SYNC_DATETIME.
  OPT_ERR_LABEL	If an error label is provided, control will branch to this label if an error occurs when trying to sync the date / time / terminals (e.g. the DCConnect Server is not running). The data part LAST_ERROR will contain the error code. If the label name is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends. The label is optional; if not specified, the script will always execute the next command step - unless the error causes TC to terminate.

  Examples:
   
    ...
    Declare ( uvYear )
    Declare ( uvMonth )
    Declare ( uvDay )
    Declare ( uvHour )
    Declare ( uvMinute )
    Declare ( uvSecond )
    ...
   
    // Don't let DCConnect unavailability end the TC session
    No_Terminate_From_DCConnect
  
    // Just sync the terminals with the DCConnect Server using its current date and time.  If error, branch to SyncError label
    Sync_Date_Time ( SYNC_TERMINALS, SyncError ) 
  
    // Get the date and time from a web service and then parse it into uvYear, uvMonth, uvDay, uvHour, uvMinute, uvSecond
    // and then call the command to update the DCConnect Server time and then sync the terminals.  If error, branch to SyncError label.
    ...
    Sync_Date_Time ( SYNC_DATETIME, uvYear, uvMonth, uvDay, uvHour, uvMinute, uvSecond, SyncError ) 
  
    ...
  SyncError:
    
    // Handle error trying to sync date time
   
   

  System

    System ( RC_UV, "command"* )
    System ( RC_UV, "command"*, TIMEOUT )
    System ( RC_UV, CMD_UV, START*, LENGTH* )
    System ( RC_UV, CMD_UV, START*, LENGTH*, TIMEOUT )
  

  This function can be used to execute any operating system command or run an external command file or other application. Control is transferred to this command. TC processing blocks at this point until your command returns, or an optional time-out occurs.

  If the command reports that it executed successfully, the return code user variable you specify is filled with the text OK. If the command reports that something is wrong, the user variable contains the text FAILED.

  The LAST_ERROR data part is set to 0 if the command runs successfully, -1 if the command can not be launched, or -2 if the command times out.

  Note: In version 3.0.8L (June 2013) of TC an enhancement was made to the System command to launch applications in a true 64-bit commad environment if it is detected that TC is running on a 64-bit version of Windows. TC looks for %windir%\sysnative\cmd.exe and uses that if it exists. Otherwise it uses %windir%\system32\cmd.exe. (Note: %windir% is typically c:\windows.) It is necessary for TC to use the 'sysnative' syntax to force the 64-bit environment because, since TC is a 32-bit application, Windows will by default, actually redirect references to %windir%\system32 so that they go to %windir%\syswow64 instead (WOW64 = Windows-on-Windows64). Therefore by default the cmd.exe that is start will be the one for the 32-bit environment. There are certain commands, such as msg.exe, and functions that exist/work only in the 64-bit environment. When running in the 32-bit environment, a directory listing of %windir%\system32 is redirected by Windows so that you actually see %windir%\syswow64.

  RC_UV	The user variable in which you want the return code to be placed. Specify as UVn or provide a user variable's alias. It returns either OK or FAILED.
  "command"*	The operating system command or application name to be run. To prevent a command from writing to the TC display screen, specify the >>NUL piping option to send standard output to the bit bucket. A user variable may be used in place of an explicit command string.
  CMD_UV	A user variable that has the content of the system command or application name to run. When a user variable is used to contain the command string the start position and length parameters are required.
  START*	The starting position within the user variable. A starting position of 0 will start at the beginning of the string.
  LENGTH*	The length of the user variable string starting from the START parameter position. A length of 0 indicates to use the entire string length.
  TIMEOUT	Optional timeout specified in seconds. Zero (or absence of the parameter) indicates "wait forever" for the command to execute. If a non-zero timeout is specified and the command runs beyond that number of seconds then TC will attempt to kill the command process and then will log an error and continue with the next script command. You can use the LAST_ERROR value to determine after the fact if a timeout occurred.

  Example:
   
    // Receive a file from VM.
    // Log an error message if it fails.
    System( SysRC, "receive badges.dat badges dat a (crlf ascii")
   
    If ( SysRC == "FAILED" )
      Log_Error("Receive of badge data from VM failed")
   
    // Repeat above command using user variable
    Set_UV_Kbd_Data (SysCmd, "receive badges.dat badges dat a (crlf ascii")
   
    // Use the entire string contained in the user variable
    // starting at the first position, and a 30 second timeout
    System (SysRC, SysCmd, 0, 0, 30 )
    
    If ( LAST_ERROR  == "-2" )
       do logic to handle timeout....
     .
     .
     .
  

  TC_Get_Active_Sessions

    TC_Get_Active_Sessions ( uvForListOfControllerIDs )
  

  This command fetches the list of controller IDs that are associated with every active TC session. Controller IDs (which can be 1 or two characters in length) in the list are separated by commas. To help simplify parsing logic, the last controller ID in the list is also followed by a comma. There are no spaces in the returned list. If no TC sessions are active, the return UV will be empty.

  TC sessions that are starting up or shutting down are not considered to be active and therefore are not included in the list.

  uvForListOfControllerIDs

  User variable that will contain the comma delimited list of controller IDs of active TC sessions, upon completion of the command.

  Example:
   
    Declare ( ActiveSessions ) 
    Declare ( Msg )
    Declare ( NextSession ) 
    Declare ( ProcessID )
  
    ...
  
    TC_Get_Active_Sessions ( ActiveSessions )
  
  GET_NEXT_SESSION:
  
    // Extract the first controller Id before the first comma.  Everything after that first comma will replace what was
    // originally in ActiveSessions.
    Parse_UV  ( ActiveSessions, NextSession, ",", ActiveSessions ) 
    Format_UV ( NextSession, STRIP_ALL_CHARS, " " )
  
    If ( NextSession == "" )
      Goto ( DONE_WITH_LIST ) 
  
    TC_Get_Session_Values ( NextSession, "PROCESS_ID", ProcessID, ";" )
  
    Set          ( Msg, "Process ID for TC session " )
    Append_UV_UV ( Msg, NextSession )
    Append       ( Msg, " = "       )
    Append_UV_UV ( Msg, ProcessID   )
  
    GOTO ( GET_NEXT_SESSION )
  
  DONE_WITH_LIST:
    ...
  
  

  TC_Get_Session_Values

    TC_Get_Session_Values ( controllerID*, attributeList*, uvValues, "delimiter" | CTRL_CODE | uvDelimiter )
    TC_Get_Session_Values ( controllerID*, attributeList*, uvValues, "delimiter" | CTRL_CODE | uvDelimiter,  errorLabel )
  

  This command obtains the values for one or more attributes of a single TC session, given that session's controller ID. A list of semicolon delimited attributes can be provided for the second parameter and the values for those attributes are returned in the user variable specified by the third parameter, separated by the delimiter specified by the fourth parameter.

  The possible session attribute names are:

  • ALARM_TIME - When there are any StartTime scripts defined, this is the time that the next StartTime script is scheduled to run.
  • DATABASE - The name of the database that the TC session is connected to, if any.
  • DATABASE_TYPE - One of the following: DB2, ODBC or NONE.
  • DESCRIPTION - This is the text provided by the Description command for the TC session, if it is used. If not used, this value is empty.
  • EMUL_SHORT_NAME - This is the one character PComm session identifier that was specified via the /SESSION command line parameter or Session script command for this TC session, if it was used. If not used, this value is empty.
  • EMUL_TYPE - This will be one of PCOMM, CM or NONE based on the /EMULTYPE command line parameter or EMULTYPE script command. If neither is used, this value is set to NONE.
  • LAST_EVENT - This returns a description of the last script that was run. This is the same information that is written to the top section of a TC session window, such as:
    • TIMEOUT( nnn ms )
    • INTERVAL( nnn ms )
    • LOG ON
    • LOG OFF
    • StartWebService
    • MAILBOX TRANSACTION SEQ: nnnnnnnn FUNCTIONGROUP: xyz TERM_NAME: ttttt....
    • ...
  • MAILBOX - This is the name of the DCConnect mailbox to which the TC session is connected if it used the /MAILBOX= command line parameter or the MAILBOX script command.
  • PROCESS_ID - This is the Windows process ID for the TC session. It is the same value that is shown in parentheses at the end of the title bar of the TC session window.
  • SCRIPT - This is the filename of the TC script that is being run including whatever path was provided on the command line, if any.
  • STATUS - Can be one of NOT_RUNNING, STARTING, RUNNING or STOPPING indicating the state of the TC session.
  • TRACE_ACTIVE - This indicates whether TC script processing is being written to a trace file and will have a value of TRUE or FALSE.

  Note that the values for SCRIPT, MAILBOX, EMUL_SHORT_NAME, EMUL_TYPE, DATABASE, DATABASE_TYPE and ALARM_TIME are the same that are shown on the Session popup of a TC session.

  controllerID*	The one or two character controller ID of the TC session for which the attribute values are to be obtained. A user variable may be used in place of a hard-coded controller ID.
  attributeList*	A list of one or more attribute names (described above) for which the values should be fetched. If more than one attribute value should be obtained then each attribute name should be separated by a semicolon. A semicolon after the last attribute name is optional.
  uvValues	A user variable that, upon successful return, will be filled in with the specified attribute values separated by the delimiter that is specified as the fourth parameter. If only one attribute value is to be returned, it is still followed by the specified delimiter. In addition, if an error occurred, a list is still returned with each attribute value being empty, but followed by the specified delimiter; so parsing based on that delimiter should still succeed, returning an empty value for each attribute.
  "delimiter"	The fourth parameter, the delimiter to use to separate returned attribute values, can be a constant string enclosed in double quotes. The enclosing double quotes are not considered part of the delimiter.
  CTRL_CODE	The fourth parameter, the delimiter, can also be one of the predefined TC control codes. For a list of valid control codes please see Append_UV_Kbd_Data / Append.
  uvDelimiter	The fourth parameter, the delimiter, can also be a user variable which contains the delimiter character or string to use.
  errorLabel	The default label to branch to in the event of an error. If the label is the name of a subroutine, the subroutine is called instead of a Goto being used, and control returns to the next command when the subroutine ends. The label is optional; if not specified, the script always execute the next command step. Possible error situation include an invalid controller ID or invalid attribute name. An error will be written to the TC session's error log (TC2ERRx.LOG) and the LAST_ERROR data part will be set as follows: -501 (DCX_DOES_NOT_EXIST) - If the controller ID is invalid -534 (DCX_STR_NOT_FOUND) - One of the attribute names is not valid

  Examples:
   
    Declare ( ActiveSessions ) 
    Declare ( Msg )
    Declare ( NextSession ) 
    Declare ( ProcessID )
    Declare ( AttributeList )
    Declare ( ValueList )
    Declare ( Delimiter )
    Declare ( Status )
    Declare ( TraceActive )
    Declare ( LastEvent )
  
    ...
  
    TC_Get_Active_Sessions ( ActiveSessions )
  
  GET_NEXT_SESSION:
  
    // Extract the first controller Id before the first comma.  Everything after that first comma will replace what was
    // originally in ActiveSessions.
    Parse_UV  ( ActiveSessions, NextSession, ",", ActiveSessions ) 
    Format_UV ( NextSession, STRIP_ALL_CHARS, " " )
  
    If ( NextSession == "" )
      Goto ( DONE_WITH_LIST ) 
  
    // Request a single attribute, the PROCESS_ID, for the TC session
    TC_Get_Session_Values ( NextSession, "PROCESS_ID", ProcessID, ";" )
  
    Set          ( Msg, "Process ID for TC controller ID " )
    Append_UV_UV ( Msg, NextSession )
    Append       ( Msg, " = "       )
  
    // Remove the semicolon that follows the processID, putting the result back into the processID variable
    Parse_UV     ( ProcessID, ProcessID, ";", DISCARD )
    Append_UV_UV ( Msg, ProcessID   )
  
    Log_Error ( Msg, INFO )
  
    // Now request the STATUS, TRACE_ACTIVE and LAST_EVENT values for the session
    Set ( AttributeList, "STATUS;TRACE_ACTIVE;LAST_EVENT" )
  
    // Set the delimiter to a unique value
    Set ( Delimiter, "|!|" )
    TC_Get_Session_Values ( NextSession, AttributeList, ValueList, Delimiter )
  
    // Parse out each of the attribute values, returning the shortened list to the ValueList variable
    Parse_UV ( ValueList, Status,      Delimiter, ValueList )
    Parse_UV ( ValueList, TraceActive, Delimiter, ValueList )
    Parse_UV ( ValueList, LastEvent,   Delimiter, ValueList ) 
  
    // Use the parsed values
    ...
  
    GOTO ( GET_NEXT_SESSION )
  
  DONE_WITH_LIST:
    ...
  
  

  TC_Send_Session_Command

    TC_Send_Session_Command ( controllerID*, sessionCommand*, uvReturnCode )     
    TC_Send_Session_Command ( controllerID*, sessionCommand*, uvReturnCode,  errorLabel )
  

  This script command is used to send one of the following session commands to a specific TC session, identified by its controller ID:

  • SHUTDOWN_ABNORMAL - Tells the TC session to do an abnormal shutdown which is to end immediately without running the log off script.
  • SHUTDOWN_NORMAL - Tells the TC session to do a normal shutdown which ends the currently running script immediately but does run the log off script before shutting down, if one is defined.
  • SHUTDOWN_WHEN_IDLE - Tells the TC session to shutdown when the current script is done running, if any is running, then it runs the log off script before shutting down, if one is defined.
  • TRACE_OFF - Turns off script tracing.
  • TRACE_ON - Turns on script tracing.

  controllerID*	The one or two character controller ID of the TC session to which the command will be sent. A user variable may be used in place of a hard-coded controller ID.
  sessionCommand*	One of the TC session commands listed above. A user variable may be used in place of a hard-coded command.
  uvReturnCode	A user variable that will contain a return code indicating whether the command was successful sent. A successful send does not guarantee that the command was executed by the specified TC session; it only indicates that the request was posted to that session's memory for it to act on. The TC_Send_Session_Command command could be used to verify if the session's STATUS or TRACE_ACTIVE setting has changed as requested. If the command is successfully sent, the return code is set to 0 (DCX_NO_ERROR). Possible errors include: -1 (DCX_NOT_RUNNING) - If the specified session is not currently running -501 (DCX_DOES_NOT_EXIST) - If the controller ID is invalid -534 (DCX_STR_NOT_FOUND) - The specified session command is not valid
  errorLabel	The default label to branch to in the event of an error. If the label is the name of a subroutine, the subroutine is called instead of a Goto being used, and control returns to the next command when the subroutine ends. The label is optional; if not specified, the script always execute the next command step.

  Examples:
   
    Declare ( ActiveSessions ) 
    Declare ( Msg )
    Declare ( NextSession ) 
    Declare ( ourSessionID )
    Declare ( returnCode )
    
  
    ...
  
    TC_Get_Active_Sessions ( ActiveSessions )
  
    // Find out our own session ID
    Set_UV_Ctrl_ID ( ourSessionID )
  
  GET_NEXT_SESSION:
  
    // Extract the first controller Id before the first comma.  Everything after that first comma will replace what was
    // originally in ActiveSessions.
    Parse_UV  ( ActiveSessions, NextSession, ",", ActiveSessions ) 
    Format_UV ( NextSession, STRIP_ALL_CHARS, " " )
  
    If ( NextSession == "" )
      Goto ( DONE_WITH_LIST ) 
  
    // Our own controller ID will be in the list, so we skip since we don't want to shut ourselves down.
    If ( NextSession == ourSessionID )
      Goto ( GET_NEXT_SESSION )
  
    // Send the SHUTDOWN_WHEN_IDLE command to the session.  If an error occurs, go to the SEND_ERROR label
    TC_Send_Session_Command ( NextSession, "SHUTDOWN_WHEN_IDLE", returnCode, SEND_ERROR )
  
    GOTO ( GET_NEXT_SESSION )
  
  SEND_ERROR:
  
    Set          ( Msg, "Error sending shutdown command to session " )
    Append_UV_UV ( Msg, NextSession ) 
    Append       ( Msg, "return code = " )
    Append_UV_UV ( Msg, returnCode )
    Log_Error    ( Msg )
  
  DONE_WITH_LIST:
    ...
  
  

  Title

    Title ( TEXT )
  

  This command sets the text to be used as a title of the TC sessions that run the script. This descriptive text is shown on the window title bar and in the task list for each session. This makes it easier to tell which session you are observing.

  TEXT	Up to 75 characters to describe the function of the sessions that are processing the script.

  Example:
   
    Title ( "Remote Badge Validation" )
  

  Trace

    Trace
    Trace( State )
  

  This command is used to turn on execution tracing mode for debugging purposes. If the Trace setting (no parentheses) is included anywhere in the command script file, TC creates a trace file (for example, TC2TRCA.001.) containing a chronological listing of all commands executed. Included is information on the contents of the user variables at entry to the script, updated values of the user variables after each command that can affect them, the transaction record being processed, and the SQL statement and any error messages logged.

  Note: TC writes trace information after the command is executed so that it can show which user variable were affected by the command. So if you ever observe a situation where the TC script is suspended, perhaps waiting on a database operation, the last command you will see in the trace is the last one that completed successfully; the command that is suspended will not yet be in the trace output.

  At certain key points such as the start of execution of a script, all non-empty user variables are shown in the trace.

  The TRACE output file is formatted with indenting to show subroutine levels, and shows approximately how many milliseconds the command took to process. Indentation also increases whenever a do-while loop is entered. However, if the script execution branches out of the middle of a do-while loop, the indentation does not return to the level it was outside of the do-while loop. (This is purely an issue with trace output and does not indicate that TC has permanently incremented some kind of internal stack level).

  If any Trace setting (no parentheses) is included in the command script file, all execution with that script will be in trace mode (except those blocks of code exempted from tracking by the Trace(OFF) / Trace(ON) executable commands). To end trace mode, click the On menu item in the Trace pull-down menu to toggle it off. If the Trace command is in the script file, you may want to comment it out so future start-ups will not come up in trace mode.

  On OS/2, the trace file names have the format:

    TC2TRCc.LOG
  

  where 'c' is the controller ID of the TC session being traced. The trace file will continue to grow as long as tracing is turned on, possibly consuming all available hard drive space. Therefore, be sure to turn tracing off as soon as it is no longer needed.

  On Windows a more sophisticated tracing mechanism has been implemented. A separate program, TCTRACE.EXE, handles the output to trace files on behalf of all TC sessions. For each TC session with a unique controller ID, TCTRACE.EXE uses a series of trace logfiles of a finite size in order to limit the amount of hard drive space that the trace output consumes. The trace file names have the format:

    TC2TRCc.nnn
  

  where 'c' is the controller ID of the TC session being traced and 'nnn' is a numeric value from '000' to '999'.

  If more than one TC session use the same controller ID, then TC trace will add a lower case letter before the '.nnn' so that each TC session is associated with a set of unique log file names. For example, if three sessions were using controller ID 'A', the following trace file names could be used:

    TC2TRCA.nnn
    TC2TRCAa.nnn
    TC2TRCAb.nnn
  

  However, there is no guarantee what extra letter, if any, is associated with each TC session. In fact, during the course of a TC session this letter may change if there is a temporary slow down in the system which causes the connection between the TC session and the TRCTRACE program to be closed and reopened. Therefore, if you have to enable tracing, it is recommended that you use the CNTLR command in your script files or the /CNTLR command line option to specify a unique controller ID for each TC session.

  By default, each trace file will grow to approximately 1,024,000 bytes and by default TCTRACE will keep up to 9 trace files for each session - plus the one it is currently writing to.

  The default size and number of trace files that are preserved at a time can be changed by creating a TCTRACE.INI file (in the directory defined by the TC2 environment variable) and specifying the NUM_TRACE_FILES and/or TRACE_FILE_SIZE. For example:

    NUM_TRACE_FILES = 20
    TRACE_FILE_SIZE = 5
  

  NUM_TRACE_FILES can be in the range 1 to 999. This actually specifies the number of trace files that are preserved; the currently growing file is not included in that count. If this keyword is not included, the default number of files is as it was in the past (9). Although in the past, the currently growing file was not treated separately.

  TRACE_FILE_SIZE specifies a multiple of Megabytes (0x100000 = 1,048,576 bytes). It can be in the range from 1 to 99 MB. If this keyword is not included, the default size is what it was in the past (0xfa0000 = 1,024,000 bytes).

  The values specified in TCTRACE.INI apply to all sessions that are tracing. However, individual TC sessions can override those values using the TRACE_SIZE command in the script. Please see Trace_Size for more information.

  State

  The stopping and starting of TRACE can be controlled while executing in a command script by setting it to one of the following states: OFF - Stop TRACE ON - Restart TRACE Note that the TRACE command with the OFF/ON parameter can only be used within executable script code, and only has any effect if the current mode of operation for the TC session is to have tracing enabled. In other words, the OFF/ON parameters are intended for use in disabling Trace mode in sections of your scripting that you know perform correctly and are of little value to have cluttering a trace log file. Using the OFF and ON parameters tells TC that tracing should disabled for a specific section of scripting code - those that are executed between the TRACE (OFF) and TRACE (ON) commands.

  Example:
   
    Trace( ON )
  

  Trace_Delay_Limit

    Trace_Delay_Limit ( DelayTimeMax, SampleTime, ReenableTime )
  

  This command overrides the default values for detection of slowness in tracing. Normally, tracing adds a negligible amount of time to execution of a script. But under certain conditions on the Windows sytem the pipes/disk/etc. involved can be slow to accept work and then the tracing of a command can taken an abnormally long period of time (as shown in the line-by-line trace timings in the trace file).

  By default, if the TC session measures that it has taken in excess of 5 seconds during a 60-second sampling interval to re-try writes to the trace file then it will disable tracing for 60 minutes (to allow transient conditions on Windows to subside).

  This command can be used to override the 5/60/60 settings with other time values, or disable the monitoring completely.

  DelayTimeMax	Specifies the maximum number of seconds of accumulated delay time spent waiting for tracing to work during the sampling period. This can be 0 to disable checking, or 1-60 seconds.
  SampleTime	Specifies the number of seconds for the sampling period. This can be 10-600 seconds.
  ReenableTime	Specifies the number of minutes after automatic disabling of trace that it will be re-enabled. This can be 0 to never reenable, or 1-480 minutes.

  Trace_Size

    Trace_Size ( Num_Trace_Files [, Trace_File_Size]   )
  

  This command, which is only useful on Windows (although it will still be accepted by the compiler on OS/2), is used to specify the number and size of trace files maintained for the current TC session. It overrides the default that applies to all TC sessions but only for the script(s) in which the command is used. For a discussion of the default global size and default number of trace files and how that can be changed using TCTRACE.INI please see Trace.

  The Trace_Size command is useful if you have many different TC sessions but you only want to capture a large amount of trace data for specific sessions.

  Note: Using the Trace_Size command does not actually tell TC to turn on tracing. Trace_Size will only be meaningful if the Trace command is also used in the script or if tracing is turned on from the TC User Interface.

  Num_Trace_Files	Specifies the number of trace files that TCTRACE will preserve in addition to the one it is currently writing to. This can be a number from 1 to 999.
  Trace_File_Size	This optional parameter specifies a multiple of megabytes (0x100000 = 1,048,576 byes) indicating the approximate maximum size TCTRACE will let an individual trace file grow to before it starts with the next trace file in the sequence.

  Examples:
   
    // Specify that this TC session will have maintained on its behalf, up to 20 trace
    // files of the default size (1,024,000 bytes) or whatever size may have been
    // specified for the TRACE_FILE_SIZE in TCTRACE.INI
   
    Trace_Size (20)
   
    // Specify that this TC session will have maintained on its behalf, up to 50 files
    // of 5MB each.
   
    Trace_Size (50, 5)
   
  

  Update_DB_Table

    Update_DB_Table( QUALIFIER.TABLE_NAME* )
  

  This is the first command of the series required to UPDATE a row (record) of a database table. For additional information refer to Setup_Update_Field, Update_Where, and Perform_Update.

  Note:

  Once you start creating your UPDATE SQL statement with this command, you should complete construction of the command and perform it without calling subroutines or doing any other unrelated commands. Other commands may cause side effects in the storage used to create your SQL statement.

  *The parameter can be specified as a quoted or unquoted string, a user variable, or a data part. Prior to version 3.1.0e, this could only be a quoted or an unquoted string.

  QUALIFIER	An optional qualifier in case the table is associated with a user ID other than that logged on to the database at this workstation. Leave this off if the tables are owned by the current user ID.
  TABLE_NAME	The name of the table within the database.

  Examples:
   
    // Use the qualifier and table directly
    Update_DB_Table( PERSONNEL.EMPLOYEES )
  
    // Use a variable for the parameter
    Set ( UV1, "PERSONNEL.EMPLOYEES" )
    Update_DB_Table ( UV1 )
  
  

  Update_Where

    Update_Where( COLUMN, COL_TYPE, COMPARISON, DATA_PART, START, LENGTH )
    Update_Where( COLUMN, COL_TYPE, COMPARISON, DATA_PART, START, LENGTH,
                     PREFIX )
    Update_Where( COLUMN, COL_TYPE, COMPARISON, DATA_PART, START, LENGTH,
                     PREFIX, SUFFIX )
  

  This is the third command in the series used to UPDATE a row (record) or rows in a database table. It is used to specify the WHERE condition for the update (that is, the criteria for selecting which row or rows should have their columns modified, with the columns being specified in Setup_Update_Field commands).

  See also Update_DB_Table, Setup_Update_Field, and Perform_Update.

  COLUMN	The table column name.
  COL_TYPE	The type of data stored in the column: NUMERIC, CHARACTER, TIME, DATE, or TIMESTAMP. The type tells TC whether to put quotes around the data (CHARACTER or time/date types) and whether to add delimiters and the century to time/date types. For time/date types, the input data can be in the form sent by the terminal or it can already have delimiters in place. Data for a TIME type column must be in the form HHMMSS (as it comes from the terminal), HH:MM:SS, or 'HH:MM:SS'. Data for a DATE type column must be in the form YYMMDD (as it comes from the terminal), YYYY/MM/DD, or 'YYYY/MM/DD'. Data for a TIMESTAMP type column must be in the form YYMMDDHHMMSS (as it comes from the terminal), YYYY-MM-DD-HH.MM.SS, or 'YYYY-MM-DD-HH.MM.SS'.
  COMPARISON	The logical comparison operator used between the column name and the data (PREFIX+DATA_PART+SUFFIX). Possible values include =, <>, >, >=, <=, <.
  DATA_PART	This specifies one of various predefined parts of the terminal transaction or other information that becomes the criteria for the Update Where clause. The predefined parts are shown for this parameter in Data Parts The data parts that are valid vary depending on whether the TC session is currently running in transaction, validation or data request mode. If the datapart is empty (typically a user variable or transaction field) it will be put into the SQL string as an empty string ('') for CHARACTER columns or as NULL for any other type of column.
  START	The starting position within the specified data part. 0 is the beginning of the data.
  LENGTH	The length of data to use from the data part, starting at the START position. Refer to Data Parts for the meaning of a 0 length for a given data part. It may be ignored, it may mean return no data or it may mean take all data from the START position.
  PREFIX	An optional string to append as a prefix to the data from the DATA_PART. The data used for the command is formulated by appending the three elements: PREFIX+DATA_PART+SUFFIX For example, to add a number from the transaction to the current value in the QUANTITY column, specify the DATA_PART as TXNDATA or TXNFIELDn and set the PREFIX to QUANTITY+. If you do not want a prefix but do want a suffix, specify the PREFIX to be NULL. You cannot have a suffix without a prefix as a place holder in the command.
  SUFFIX	An optional string to append as a suffix to the data from the DATA_PART. The data used for the command is formulated by appending the three elements: PREFIX+DATA_PART+SUFFIX You can specify the SUFFIX as NULL, which is equivalent to not specifying a SUFFIX at all and simply ending the command string with the ending ')'.

  Example:
   
    // Update the row(s) where PART_NUMBER equals the 2nd ';'-delimited field
    // of the transaction AND the WAREHOUSE column in the table is equal to 5
    // (this last AND clause is contained in the SUFFIX, after a NULL PREFIX).
    Update_Where ( PART_NUMBER, NUMERIC, = , TXNFIELD2, 0, 0, NULL, AND WAREHOUSE=5 )
  

  Use_Adjusted_Xact_Time

    Use_Adjusted_Xact_Time
  

  This command tells TC to use the adjusted date and time fields from the transaction record for the original transaction date and time data parts (e.g. YEAR, MONTH, DAY, HOUR, MINUTE, SECOND, ...) rather than the terminal date and time fields in the transaction record. If necessary, you can still access the terminal date and time fields of the transaction record using the date and time data parts with the TERM prefix (e.g. TERMYEAR, TERMMONTH, TERMDAY, ...)

  In addition, the XACT_AGE data part and the Xact_Age script command are affected by the Use_Adjusted_Xact_Time command; when it is in effect the transaction age is calculated using the server adjusted date and time.

  When you have terminals that are in different time zones from the server, the terminal date and time fields of the transaction record will contain the date and time of the terminal's time zone; but the adjusted date and time fields will contain the terminal's date and time adjusted to the server's time zone. This is necessary when calculating transaction age because the age is always relative to the server time.

  This command can only be used when the versions of both Transaction Connection and the DCConnect Server are from October 2004 or later.

  Here is the complete list of data parts that are affected by this command:

  • DATE4

  • DATE

  • TIMESTAMP4

  • TIMESTAMP

  • YEAR4

  • YEAR

  • MONTH

  • DAY

  • TIME

  • HOUR

  • MINUTE

  • SECOND

  • XACT_AGE

  At all times, but particularly when this command is in effect, the following data parts can be used to access the terminal date and time fields (non-adjusted) from the transaction record.

  • TERMDATE4

  • TERMDATE

  • TERMTIMESTAMP4

  • TERMTIMESTAMP

  • TERMYEAR4

  • TERMYEAR

  • TERMMONTH

  • TERMDAY

  • TERMTIME

  • TERMHOUR

  • TERMMINUTE

  • TERMSECOND

  At all times, but particularly when this command is not in effect, the following data parts can be used to access the adjusted date and time fields from the transaction record:

  • ADJDATE4

  • ADJDATE

  • ADJTIMESTAMP4

  • ADJTIMESTAMP

  • ADJYEAR4

  • ADJYEAR

  • ADJMONTH

  • ADJDAY

  • ADJTIME

  • ADJHOUR

  • ADJMINUTE

  • ADJSECOND

  Example:
   
    Use_Adjusted_Xact_Time
  

  UV_Math

    UV_Math( UV_TARGET, OPERATOR, CONSTANT, FORMAT )
    UV_Math( UV_TARGET, OPERATOR, UV_SOURCE, FORMAT )
  

  UV_Math is used to treat a user variable as a numeric value and to manipulate its contents as such. With the UV_Math function, you can add to, subtract from, multiply, divide with a real number result, divide with an integer result, perform a modulus operation (remainder after integer divide) or set a user variable with another user variable or a constant value.

  The operands and result are all limited to 19 significant digits.

  Possible variations are presented as follows, where UVx is the target user variable, UVy is the source user variable, and Z is a constant (for example, 1.0, 15.85, and so forth).

  • Add to the current contents of a user variable (UVx) the value of another user variable (UVy):

      UVx = UVx + UVy     Example:  UV_Math( UV1, +, UV2 )
    

  • Add to the current contents of a user variable (UVx) a constant value (Z):

      UVx = UVx + Z       Example:  UV_Math( UV1, +, 1.0 )
    

  • Subtract from the current contents of a user variable (UVx) the value of another user variable (UVy):

      UVx = UVx - UVy     Example:  UV_Math( UV1, -, UV2 )
    

  • Subtract from the current contents of a user variable (UVx) a constant value (Z):

      UVx = UVx - Z       Example:  UV_Math( UV1, -, 1 )
    

  • Multiply the current contents of a user variable (UVx) by the value of another user variable (UVy):

      UVx = UVx * UVy     Example:  UV_Math( UV1, *, UV2 )
    

  • Multiply the current contents of a user variable (UVx) by a constant (Z) and format the results to be 7 characters wide with 2 digits to the right of the decimal point.

      UVx = UVx * Z       Example:  UV_Math( UV1, *, 15.83, 7.2 )
    

  • Divide the current contents of a user variable (UVx) by the value of another user variable (UVy) with the result being a real number:

      UVx = UVx / UVy     Example:  UV_Math( UV1, /, UV2 )
    

  • Perform real number division of the current contents of a user variable (UVx) by a constant (Z) and format the results to be 7 characters wide as an integer with no digits to the right of the decimal point.

      UVx = UVx / Z       Example:  UV_Math( UV1, /, 2.0, 7.0 )
    

  • Divide the current contents of a user variable (UVx) by the value of another user variable (UVy) with the result being an integer:

      UVx = UVx \ UVy     Example:  UV_Math( UV1, \, UV2 )
    

    When integer division is done, the result is truncated to an integer rather than rounded. For example, if UV1 was 8 and UV2 was 3 before the integer division operation, after the operation UV1 would be set to 2. Use the modulus operator (%) to get the remainder - which is 2 in this case.

  • Get the remainder from performing an integer divide operation on UVx by an integer stored in another user variable (UVy):

      UVx = UVx % UVy     Example:  UV_Math( UV1, %, UV2 )
    

  • Get the remainder from performing an integer divide operation on UVx by an integer constant (Z):

      UVx = UVx % Z       Example:  UV_Math( UV1, %, 2 )
    

  • Set a user variable (UVx) equal to the value of another user variable (UVy) and format the value in the process to be 5 characters wide with 3 digits to the right of the decimal point:

      UVx = UVy           Example:  UV_Math( UV1, =, UV2, 5.3 )
    

  • Set a user variable (UVx) equal to a constant (Z):

      UVx = Z             Example:  UV_Math( UV1, =, 2.0 )
    

    Note:

    This performs the same net effect as using Clear_UV and Append_UV_Kbd_Data in succession. Using UV_Math is more compact, however, for this type of mathematical manipulation.

  UV_TARGET	The target TC user variable that will provide one value for the arithmetic equation and will be overwritten with the new resulting value.
  OPERATOR	The arithmetic operator to be applied between the target and source values. Valid operators are + (add), - (subtract), * (multiply), / (divide with real number result), \ (divide with integer result), % (modulus - remainder after integer division), and = (set equal to).
  UV_SOURCE	The source TC user variable or a constant (**) (70) value to be used to modify the target user variable.
  FORMAT	An optional format string to specify how you want the numeric value to be presented to data collection terminals or to applications. The format string specifies the overall width of the formatted output, how many digits to retain after the decimal point, left- or right-justification, and so forth. Because the formatting can truncate the stored precision of the value (not just its presentation), you may want not to specify a precision on intermediate calculations and only specify the format on the final arithmetic operation. The standard precision if no format is specified has 6 digits to the right of the decimal place. The format string has 3 optional subsections: [flags][width][.precision] where: flags Can be one or more of the following. - Left-justify the result within the field width (default is right-justify). + Prefix the output value with a sign (+ or -) if the output value is of a signed type. ' ' (blank) Prefix the output values with a blank if the output value is signed and positive. The "+" flag overrides the blank flag if both appear, and a positive signed value will be output with a sign. width Is a non-negative decimal integer controlling the minimum number of characters in the output. If the number of characters in the output is less than the specified width, blanks are added on the left or right (depending on whether the "-" flag is specified) until the minimum width is reached (not useful for left-justified numbers). The width never causes a value to be truncated; if the number of characters in the output value is greater than the specified width or the width is not given, all characters of the value are in the output (subject to the precision specification). .precision Is a non-negative decimal integer, preceded by a period, that specifies the number of characters to be in the output or the number of decimal places. Unlike the width specification, the precision can cause truncation of the output value or rounding of a floating-point value. The precision specifies the number of digits after the decimal point. If a decimal point appears, at least one digit appears before it. The value is rounded to the appropriate number of digits. Specifying 0. or . or 0.0 for width.precision all indicate that nothing is to the right of the decimal point (and there isn't any decimal point either).

  Wait_Until_Unlocked

    Wait_Until_Unlocked ( ERROR_LABEL )
  

  This command causes the processing of the command file to wait until the host keyboard is unlocked and data can be safely placed on the screen. The command waits for up to one minute for the host to unlock the terminal screen. If this time period expires with the screen still locked, TC routes execution of your script to the ERROR_LABEL you provide.

  The use of the Check_Screen command is recommended to determine if the expected screen is available for use, rather than Wait_Until_Unlocked. Check_Screen allows checking for error conditions, and allows a time limit to be given for how long to wait.

  ERROR_LABEL

  An optional label to branch to when TC times out while waiting for the host screen to unlock. If no label is provided, TC will log an error and terminate if a locked or busy error occurs. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends.

  Example:
   
    //  Wait for the keyboard to be unlocked.
    Wait_Until_Unlocked ( TIMED_OUT_WAITING_FOR_UNLOCK )
  

  While (Do...While)

      While ( DATA_PART_A(START, LENGTH)  COMPARE  DATA_PART_B(START, LENGTH) )
      While ( "String" | NumericConstant        COMPARE  DATA_PART_B(START, LENGTH) )
      While ( DATA_PART_A(START, LENGTH)  COMPARE  "String" | NumericConstant )
   
      While ( DATA_PART_A                 COMPARE  DATA_PART_B )
      While ( "String" | NumericConstant        COMPARE  DATA_PART_B )
      While ( DATA_PART_A                 COMPARE  "String" | NumericConstant )
   
      While ( DATA_PART_A, START, LENGTH, COMPARE, DATA_PART_B, START, LENGTH )
      While ( "String" | NumericConstant,       COMPARE, DATA_PART_B, START, LENGTH )
      While ( DATA_PART_A, START, LENGTH, COMPARE, "String" | NumericConstant )
   
    And/Or/Not logic operators can be used to create more complex logic
    operations.  If we let C1, C2, ... stand for one of the ways of specifying a
    single comparison operation shown above, then the following examples show how
    multiple logic operations can be performed in a single While statement:
   
      While (NOT(C1))
      While (!  (C1))
      While ((C1) AND (C2))
      While ((C1) &&  (C2))
      While ((C1) &   (C2))
      While ((C1) OR  (C2))
      While ((C1) ||  (C2))
      While ((C1) |   (C2))
      While ((C1) AND NOT ((C2) OR (C3 AND C4)))
      ...
  

  The first 6 syntax definitions shown above are allowed if you are using at least fix pack E for the 1.40 version of TC.

  The use of the AND / OR / NOT logic operators are allowed only if you are using a version of TC built in November 2002 or later.

  In the second group of 3 syntax definitions shown above, the START and LENGTH values are assumed to both be 0.

  Repeatedly execute a step or group of steps while a condition remains true. The condition is a comparison between two pieces of information. The two pieces of data that are compared can independently be:

  • User variable
  • Any data part
  • A literal string constant enclosed in double quotes
  • A numeric constant which does not have to be enclosed in double quotes and which can be any base 10 number, optionally having a leading negative sign and optionally having a decimal point.

  The logical form of the comparison is:

   
    Do
     {
      Some step or steps
     }
    While  A comparison B
  

  The A and B user variables are evaluated at runtime based on the source of data you specified in your While command. The step or steps after the Do are always executed at least once prior to doing the comparison. The comparison (for example, =, >, !=, and so forth) of the two user variables is made, and if it was TRUE, the steps are repeated. This continues until the comparison is not TRUE anymore.

  The use of AND / OR / NOT logic operators (and their equivalents &&, &, ||, |, !) shown above allow you to perform and link multiple comparison and logic operations in a single While statement. For more information about what syntax rules must be followed when using these operators and how TC processes these statements, please see Using AND, OR and NOT operators in If and While Statements.

  See also Script Control Using Do...While for discussion and examples of using Do...While and enclosing braces ({}) to control the flow of your script.

  DATA_PART_A	This specifies one of various predefined parts of the terminal transaction or other information that becomes the string used for the A side of the comparison. The parts are listed in Data Parts. The data parts that are valid vary depending on whether the TC session is currently running in transaction, validation or data request mode.
  START	The starting position within the transaction data part. 0 is the beginning of the data.
  LENGTH	The length of data to use from the data part, starting at the START position. Refer to Data Parts for the meaning of a 0 length for a given data part. It may be ignored, it may mean return no data or it may mean take all data from the START position.
  "String"	The DATA_PART/START/LENGTH parameters for either the A or B sides of the comparison can be omitted and replaced with a literal string presented in double-quote marks or a NumericConstant (see below). As of version 3.1.0d, maximum string length is 128 bytes; prior to that it was 64 bytes.
  NumericConstant	Numeric constants do not have to be enclosed in double quotes and can be any base 10 number, optionally having a leading negative sign and optionally having a decimal point.
  COMPARE	Logical comparison operator for the two values. Although the data coming from terminals or from the host screen is always in character string form inside TC, you can tell TC to perform the comparison treating the values either as character strings or as numeric values, depending on what the values represent in your application. Numbers can be integers or real numbers (for example, 12, 5.87, -200.6). Comparisons as strings are symbolized in the command format as follows: Equal : == or = Greater Than: > Greater Than or Equal: >= or => Less Than: < Less Than or Equal: <= or =< Not Equal: <> or != Comparisons as numeric values are input similarly, but with a leading "#" symbol to signify that numbers are involved: Equal : #== or #= Greater Than: #> Greater Than or Equal: #>= or #=> Less Than: #< Less Than or Equal: #<= or #=< Not Equal: #<> or #!=
  DATA_PART_B	Same definition as DATA_PART_A.
  START	Starting character for string B (see DATA_PART_A).
  LENGTH	Length of source string to use for string B (see DATA_PART_A).

  Examples:
   
    // Print a line of a report 10 times.
    UV_Math( UV1, =, 1 )
    Do
     {
      Log_Data( REPORT, UV20, APPEND )
      UV_Math( UV1, +, 1)
     }
    While ( UV1 #<= 10)
   
    // The following loop should execute only 3 times
    Set_UV_Kbd_Data(uv50, "5")
    Set_UV_Kbd_Data(uv51, "Green")
    do
     {
      Log_Error("You should see this 3 times")
      UV_Math(uv50, -, 1)
      if (uv50 #== "2")
        Set_UV_Kbd_Data(uv51, "Red")
     }
    while ((uv50 #> 0) && (uv51 == "Green"))
   
  

  Workstation_Profile / WS_Profile

    Workstation_Profile( PATH_AND_FILE_NAME )
  

  If this command is used to establish the path and file name of a Personal Communications work station profile, TC will be able to start the emulator window automatically if it finds that the window associated with the short session ID is not already running. Both the automatic host session connection run at start-up of TC and the Session_Connect command use the information provided by Workstation_Profile.

  Example:
   
    //* Telnet 5250 profile to our AS/400 has
    //* been saved from the Personal Communications
    //* emulator set-up screens.
    Workstation_Profile( C:\PCOMOS2\PRIVATE\TN5250.WS )
  

  Write_To_Event_Log

    Write_To_Event_Log ( APPLICATION_NAME*, TYPE, MESSAGE* )
    Write_To_Event_Log ( APPLICATION_NAME*, TYPE, MESSAGE*, ERROR_LABEL )
  

  This command is used to log a message to the Windows event log.

  APPLICATION_NAME*	Application name used to identify the TC Session in the event log. This name shows up in the 'Source' column of the event log. The application name may be a name enclosed in double quotes or a variable containing the name. TC restricts this name to 32 characters.
  TYPE	The type may be one of ERROR, WARNING or INFO. Only the first character is checked. Enclosing double quotes are optional.
  MESSAGE*	The text of the message to be logged. This can either be a string enclosed in double quotes or a variable containing the message text. If the text is included in the command, it is limited to 255 bytes.
  ERROR_LABEL	The default label to branch to in the event of an error. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control returns to the next command when the subroutine ends. The label is optional; if not specified, the script always execute the next command step.

  Example:
   
    Write_To_Event_Log ( "TC_DOWNLOAD", WARNING, "Restarting download task" )
   
  

  Write_Xact / Write_Xact2x

    Write_Xact( FUNCTIONGROUP*, TERMNAME*, EVENT_ID, DATA_PART, START*, LENGTH* )
    Write_Xact( FUNCTIONGROUP*, TERMNAME*, EVENT_ID, DATA_PART, START*, LENGTH*, TIMESTAMP* )
    Write_Xact( FUNCTIONGROUP*, TERMNAME*, EVENT_ID, DATA_PART, START*, LENGTH*, MAILBOXLIST* | "MAILBOX1", "MAILBOX2", ... )
    Write_Xact( FUNCTIONGROUP*, TERMNAME*, EVENT_ID, DATA_PART, START*, LENGTH*, TIMESTAMP*, MAILBOXLIST* | "MAILBOX1", "MAILBOX2", ...)
  
    Write_Xact2( FUNCTIONGROUP*, TERMNAME*, EVENT_ID, DATA_PART, START*, LENGTH*, SERIAL_KEY*, PRIORITY* )
    Write_Xact2( FUNCTIONGROUP*, TERMNAME*, EVENT_ID, DATA_PART, START*, LENGTH*, SERIAL_KEY*, PRIORITY*, TIMESTAMP* )
    Write_Xact2( FUNCTIONGROUP*, TERMNAME*, EVENT_ID, DATA_PART, START*, LENGTH*, SERIAL_KEY*, PRIORITY*, MAILBOXLIST* | "MAILBOX1", "MAILBOX2", ... )
    Write_Xact2( FUNCTIONGROUP*, TERMNAME*, EVENT_ID, DATA_PART, START*, LENGTH*, SERIAL_KEY*, PRIORITY*, TIMESTAMP*, MAILBOXLIST* | "MAILBOX1", "MAILBOX2", ...)
  
    Write_Xact22( FUNCTIONGROUP*, TERMNAME*, EVENT_ID, DATA_PART, START*, LENGTH*, SERIAL_KEY*, SERIAL_KEY_2*, PRIORITY* )
    Plus other variations per Write_Xact2
  
    Write_Xact23( FUNCTIONGROUP*, TERMNAME*, EVENT_ID, DATA_PART, START*, LENGTH*, SERIAL_KEY*, SERIAL_KEY_2*, SERIAL_KEY_3*, PRIORITY* )
    Plus other variations per Write_Xact2
  
  

  This command can be used to facilitate communications between different TC sessions, or to any other DCConnect applications.

  Write_Xact sends a transaction to one or more DCConnect mailboxes in the same way that a physical DCT sends a transaction. The receiving TC session reads in the transaction as if it came from a terminal. The apparent originating terminal may or may not be online, depending on your application requirements. But it will be part of the DCConnect configuration (unless a mailbox list is used). When DCConnect receives the transaction it will look up the terminal in its configuration in order to determine to which mailboxes the transaction should be written.

  As of October 2004, TC supports the ability to specify a list of one or more mailbox names either explicitly or in a data part. When this is done, the DCConnect Server does not require that the terminal name be one that is in its configuration. This feature allows a TC script to generate transactions without having to have a 'dummy' terminal set up in DCConnect.

  Transactions sent with this command are automatically generated in Buffered mode, have the current system time and date used for the timestamp (unless overridden by the TIMESTAMP parameter), and are given a 5-digit terminal transaction sequence number that automatically cycles through the sequence 00000 to 65535.

  As of August 2015, the Write_Xact2 variation of this command supports the ability to write to DCConnect master mailbox operating in serial-keying mode. This type of master mailbox allows for load leveling among a pool of mailboxes served by the master mailbox. The SERIAL_KEY value allows the application to specify that the DCConnect server prevent parallel processing of the same key value in more than 1 pool mailbox. You may want this, for example, to ensure that all of the transactions for issues, receipts from production, and backflushing for a particular work order are posted in the chronological sequence in which the work was performed. The PRIORITY value allow having a recently-added transaction skip to the head of the queue. This would typically be used to have live inquiry transactions processed ahead of back-end ERP system postings.

  As of June 2018, Write_Xact22 and Write_Xact23 are extensions of Write_Xact2 that allow a second, or a second and third, serial key. These can be used to extend the sequencing from a master mailbox to also consider secondary/tertiary serialization values such as 'from' item-location and 'to' item-location. Thus, you can ensure that transactions that affected the physical inventory of a item-location are posted in the sequence they were physically performed.

  Note:

  1. The receiving session must be running in transaction mode; Write_Xact cannot send a remote validation request or data request.

  2. Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a TC user variable by using the user variable's name or the notation UVn, where n ranges from 1 to 250 or the maximum defined by Define_UVs.

     The timestamp and the mailbox list can come not only from a user variable but also from any data part.

  FUNCTIONGROUP	If a mailbox list is not provided, this parameter is actually not used because the DCConnect Server will fill in the transaction structure when it receives the write transaction request from TC. It looks up the terminal name that is provided and fills in the function group name based on the function group to which the terminal is assigned in the DCConnect configuration. However, if one or more mailboxes is specified in this command, the DCConnect Server will not fill in the function group name automatically; it will pass along whatever you provide for this value without validating it against the DCConnect configuration. In all cases, TC requires this field be part of the Write_Xact command.
  TERMNAME	If a mailbox list is not provided, this must be a valid terminal name configured in DCConnect. In this case, this is used by DCConnect to route the transaction to the mailboxes configured in DCConnect. TERMNAME can be specified as CURRENT to automatically use the terminal name of the current terminal - but only if TC is processing a transaction or a validation request. (**) (71) A user variable name may also be specified for this parameter. In this case that user variable can contain the actual terminal name or the keyword CURRENT. The trace of this command will show what the final terminal name resolves to using the format: [ UVName: ] [ CURRENT: ] Termname
  EVENT_ID	The transaction event ID to be sent with the transaction data. This is used by DCConnect to route the transaction to the mailboxes configured in DCConnect. Use any of the key ID names from the following table or the corresponding numeric value: ID ID ID ID ID ID ID -- -- -- -- -- -- -- 1 F1 21 F21 41 PF11 61 DI4 81 RGN9 101 RGN29 121 TOD 2 F2 22 F22 42 PF12 62 DI5 82 RGN10 102 RGN30 3 F3 23 F23 43 SHIFT_PF1 63 DI6 83 RGN11 103 RGN31 4 F4 24 F24 44 SHIFT_PF2 64 DI7 84 RGN12 104 RGN32 5 F5 25 F25 45 SHIFT_PF3 65 RES2 85 RGN13 105 RGN33 6 F6 26 F26 46 SHIFT_PF4 66 RES3 86 RGN14 106 RGN34 7 F7 27 F27 47 SHIFT_PF5 67 RES4 87 RGN15 107 RGN35 8 F8 28 F28 48 SHIFT_PF6 68 RES5 88 RGN16 108 RGN36 9 F9 29 BADGE 49 SHIFT_PF7 69 RES6 89 RGN17 109 RGN37 10 F10 30 CLOCKING 50 SHIFT_PF8 70 RES7 90 RGN18 110 RGN38 11 F11 31 PF1 51 SHIFT_PF9 71 RES8 91 RGN19 111 RGN39 12 F12 32 PF2 52 SHIFT_PF10 72 RES9 92 RGN20 112 RGN40 13 F13 33 PF3 53 SHIFT_PF11 73 RGN1 93 RGN21 113 ADDL1 14 F14 34 PF4 54 SHIFT_PF12 74 RGN2 94 RGN22 114 ADDL2 15 F15 35 PF5 55 GP1 75 RGN3 95 RGN23 115 ADDL3 16 F16 36 PF6 56 RES1 76 RGN4 96 RGN24 116 ADDL4 17 F17 37 PF7 57 DI0 77 RGN5 97 RGN25 117 ADDL5 18 F18 38 PF8 58 DI1 78 RGN6 98 RGN26 118 ADDL6 19 F19 39 PF9 59 DI2 79 RGN7 99 RGN27 119 ADDL7 20 F20 40 PF10 60 DI3 80 RGN8 100 RGN28 120 ADDL8
  DATA_PART	This specifies one of various predefined parts of the terminal transaction or other information that becomes the string used for the data area of the transaction. The valid data parts are listed in Data Parts. The data parts that are valid vary depending on whether the TC session is currently running in transaction, validation or data request mode. As of October 2004, the data can be up to 750 bytes in length, provided the version of the DCConnect Server that is running is also from October 2004 or later.
  START*	The starting position within the data part. 0 is the beginning of the data.
  LENGTH*	The length of data to use from the data part, starting at the START position. Refer to Data Parts for the meaning of a 0 length for a given data part. It may be ignored, it may mean return no data or it may mean take all data from the START position.
  SERIAL_KEY*	For the suffix 2 version of the command, this is the string to be used by the DCConnect server to regulate parallel processing of transactions. For any non-empty string, only 1 pool mailbox will have an active transaction with the value, and this value cannot overlap with any SERIAL_KEY_2 or SERIAL_KEY_3 value. If an empty string is specified then multiple, parallel mailboxes may receive such a transaction.
  SERIAL_KEY_2*	For the suffix 22 version of the command, this is the string to be used by the DCConnect server to regulate parallel processing of transactions. For any non-empty string, only 1 pool mailbox will have an active transaction with the value, and this value cannot overlap with a SERIAL_KEY or SERIAL_KEY_3 value. If an empty string is specified then multiple, parallel mailboxes may receive such a transaction.
  SERIAL_KEY_3*	For the suffix 23 version of the command, this is the string to be used by the DCConnect server to regulate parallel processing of transactions. For any non-empty string, only 1 pool mailbox will have an active transaction with the value, and this value cannot overlap with a SERIAL_KEY or SERIAL_KEY_2 value. If an empty string is specified then multiple, parallel mailboxes may receive such a transaction.
  PRIORITY*	The priority in the master mailbox. A lower number is a higher priority.
  TIMESTAMP*	Optionally a timestamp can be specified to override the current date and time that TC would otherwise put into the new transaction. You can specify a hard-coded string value in the format "YYMMDDHHMMSS" or "YYYYMMDDHHMMSS" or you can specify any data part that will contain the timestamp in either of those two formats. If necessary, you can use the command Format_UV using the TIMESTAMP field type to help format the timestamp value properly. The timestamp must represent a valid date and time or DCConnect will reject the transaction.
  MAILBOXLIST*	Optionally you can provide the name of a data part that will contain the list of mailboxes when this command is performed. Mailbox names are case-sensitive and each in the list must be part of the DCConnect configuration. The mailbox names in the list in the data part must be separated by one or more spaces or commas. When using a mailbox list, the terminal name provided no longer has to be a valid terminal name in the DCConnect configuration. You cannot specify both a mailbox list data part and a literal mailbox list in the Write_Xact command. When the 7th parameter is a data part, TC is able to determine, at runtime, whether the data part contains a timestamp or a list of mailbox names by checking whether the value in the data part is a valid 12 or 14 byte timestamp. If it is not, the value is assumed to be a list of one or more mailbox names.
  MAILBOX1, MAILBOX2, ...	Optionally you can provide a literal list of one or more mailboxes into which the transaction should be written. Mailbox names are case-sensitive and each one listed must be part of the DCConnect configuration. Enclosing mailbox names in double quotes is optional. However, if one of your mailbox names happens to be the name of one of the TC data parts, that name will have to be enclosed in double quotes so that TC knows it should be treated as a literal name. When using a mailbox list, the terminal name provided no longer has to be a valid terminal name in the DCConnect configuration. You cannot specify both a mailbox list data part and a literal mailbox list in the Write_Xact command. TC distinguishes between a mailbox name and a timestamp for the 7th parameter, at compile time, by checking whether the value provided is a valid 12 or 14 byte timestamp. If it is not, the value is assumed to be a mailbox name.

  Examples:
   
    // Send a transaction that appears as if it had come from
    // terminal TSTTC_00X, event ID of F2, with the data
    // coming from all of the contents of UV1.
    Write_Xact( TSTTC_CL, TSTTC_00X, F2, UV1, 0, 0 )
   
    // Send a transaction that appears as if it had come from
    // the same terminal that originated the transaction currently
    // being processed.
    Write_Xact( CURRENT, CURRENT, F1, UV1, 0, 0 )
   
    // Do the same as the previous Write_Xact but use a time
    // stamp that was set up in a user variable (e.g. after
    // being retrieved from a database table).
    Write_Xact( CURRENT, CURRENT, F1, UV1, 0, 0, uvTimeStamp )
   
    // Send a transaction and specify that it go to the mailbox Error_Mailbox
    // and specify that the terminal name be DummyTerm and the function group
    // name be DummyFG.  Error_Mailbox is a valid mailbox name in the 
    // DCConnect configuration.  But DummyFG is not a valid function group
    // name and DummyTerm is not a valid terminal name.
    Write_Xact( DummyFG, DummyTerm, F1, UV1, 0, 0, uvTimeStamp, Error_Mailbox )
   
    // Do the same as the previous example, but build a list of 2 mailbox names
    // in UV5 instead of specifying the list in the actual Write_Xact command.
    Set_UV_Kbd_Data(UV5, "Error_Mailbox1");
    Append_UV_Kbd_Data(UV5, " ");
    Append_UV_Kbd_Data(UV5, "Error_Mailbox2");
    Write_Xact( DummyFG, DummyTerm, F1, UV1, 0, 0, uvTimeStamp, UV5 )
   
    // Do the same as the previous example, but specify the data part 
    // CURRENT_MAILBOX as the data part which contains the mailbox name.
    Write_Xact( DummyFG, DummyTerm, F1, UV1, 0, 0, uvTimeStamp, CURRENT_MAILBOX )
   
  

  WS_AddAttribute

    WS_AddAttribute ( Handle, attribName*, attribValue*, outReturnCodeUV )  
  

  This command adds an attribute name and value pair to the current node of the XML document indicated by the handle's value.

  An attribute name with a "xmlns:" (XML namespace) prefix is a special case. An attribute like "xmlns:xyz" causes the attribute's base name (e.g. "xyz") to be added to the internal namespace manager so it can be used to define namespace prefix values found on elements/nodes within the document. If you add "xmlns:..." attributes to the soap:Envelope node of a SOAP request you do not need to have WS_DefineNamespace commands in your script -- and the resulting XML document will be more compact because namespace definitions are not repeated in the document.

  Handle	User variable that must contain the handle of the web service request/response.
  attribName*	The attributes name. Generally, attributes do not have namespaces. See discussion above regarding the special case of the "xmlns:" prefix on an attribute name. This name may be passed via a user variable or as a literal string.
  attribValue*	The value to associate with the attribute name. This value may be passed via a user variable or as a literal string.
  outReturnCodeUV	User variable in which the result code of the request is returned. The return code can be: 0: No error 14: Handle is not valid -1: Non-specific error. This error usually occurs because the XML namespace prefix could not be matched, a namespace should not be used/should have been used, or the element name occurrence index could not be found under the current node. The LAST_ERROR data part is also set to this result code.

  Example:   
    
    // Add an attribute to the current node.  
    // Here it would be the soap:Envelope node where we want to list a custom namespace and have it 
    // automatically added to the internal namespace manager
    WS_AddAttribute    (respHandle, "xmlns:myns",   "http://dcconnect.com/", rc )
    
    ... Add content to soap:Body and navigate to our created note dcconn:orderLine                                                   
                                                     
    // Add attribute to current node dcconn:orderLine 
    Set_UV_Kbd_Data( attribName, "my_attr" )
    Set_UV_Kbd_Data( attribValue, "my attrib value" )
    WS_AddAttribute( handle, attribName, attribValue, rc )
   
   
  

  This results in a document that looks like:

           
  <?xml version="1.0" encoding="utf-8"?>
  <soap:Envelope 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance/" 
      xmlns:xsd="http://www.w3.org/2001/XMLSchema/" 
      xmlns:myns="http://dcconnect.com/"
      xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Header />
    <soap:Body>
      <myns:ShowOrderResponse>
        <myns:ShowOrderResult>
          <myns:orderID>123</myns:orderID>
          <myns:orderLine my_attr="my attrib value">
            <myns:line>1.000</dcconn:line>
            <myns:price>1.58</dcconn:price>
          </myns:orderLine>
        </myns:ShowOrderResult>
      </myns:ShowOrderResponse>
    </soap:Body>
  </soap:Envelope>
  

  WS_AddHTTPHeader

    WS_AddHTTPHeader ( Handle, headerKey*, headerValue* )  
  

  This command is used to add a key-value pair to the header of the HTTP request / response represented by the specified handle. This should be used for non-standard header keys. For the standard header keys ACCEPT, CONTENT_TYPE, METHOD and RESPONSE_TYPE, use the command WS_SetHTTPParameter instead.

  Handle	User variable that must contain the handle of the web service request/response.
  headerKey*	The name of the header key. This name may be passed via a user variable or as a literal string.
  headerValue*	The value to be assigned to the specified header key. This value may be passed via a user variable or as a literal string.

  Example:   
  
     Declare (handle)
     Declare (rc)
     Declare (RespHandle)
  
     Declare ( Timeout )
  
     Declare ( uvlColon )
     Declare ( uvlFSlash )
  
     Declare ( uvlUID )
     Declare ( uvlPW )
     Declare ( uvlJSONBody )
  
     Declare ( URL )
  
     set_UV_Kbd_Data ( uvlColon, ":" )
     Set_UV_Kbd_Data ( uvlFSlash, "/" )
     
     WS_CreateRequest(handle,"GetToken", rc)
   
     UV_Math( Timeout, =, 10, 0.0 )
     
     // Request token, passing in the user ID and PW in JSON format 
  
     WS_SetRequestParameter(handle, "Content_Type",  "application/json" )
     WS_SetRequestParameter(handle, "Response_Type", "application/json" )
     WS_SetRequestParameter(handle, "Method",        "POST" )
    
     // After setting the standard header keys above, set the unique header key "loginDirectory"
     WS_AddRequestHeader   (handle, "loginDirectory", "Admin" )
  
     Set_UV_Kbd_Data ( uvlUID, "SuperUser" )
     Set_UV_Kbd_Data ( uvlPW,  "B@dPa$$w0rd" )
  
     Begin_UV()
       {"username":uvlColon(X)":uvlUID(X)","password":uvlColon(X)":uvlPW(X)"}
     End_UV ( uvlJSONBody )
  
     WS_SetRequestBody     (handle, uvlJSONBody )
  
     Begin_UV()
       http:uvlColon(X):uvlFSlash(X):uvlFSlash(X)validate.ibm.com:uvlColon(X)3165:uvlFSlash(X)edg-data-service:uvlFSlash(X)login
     End_UV ( URL )
     
     // Send the request and get the response in handle RespHandle.
     // Any error message can be returned in gLarge1 user variable. 
     WS_SendRequest(handle, URL, rc, RespHandle, Timeout, gLarge1 )   
     
     If( rc #== 0 )
     {   
        ... Handle the response
     }
   
  

  WS_Cleanup / WSCleanup

    WS_Cleanup( WSHandleUV )
  

  This command cleans-up/destroys the storage dedicated to a web service request or response. It must be called before the end of the scriptlet that has handled or created a web service request or response.

  The LAST_ERROR data part will be set to the error code returned by the web service call; 0 indicates success. Some specific errors that might be encountered with this command include:

  • 2 = (TC generated) Unable to obtain a COM object.
  • -1 = (TC generated) Unknown error.

  WSHandleUV

  User variable that must contain the handle of the web service request/response.

  Example:
  // Processing Scriptlet for "ShowOrder" web service
  Start_WS ("ShowOrder", gHandle)
  
     Declare (varA)
     Declare (varB)
     Declare (outHandle)
     Declare (rc)
     Declare ( OrderID )
     Declare ( OrderDate )
     
     WS_EnterElement(gHandle,"soap:Body", 1, rc)
     
     WS_EnterElement(gHandle,"tns:ShowOrder", 1, rc)
  
     WS_GetElement (gHandle, "tns:orderID", OrderID, rc)
     
     // Create a response to the received request.
     // The web service table indicates that the response is
     // in SOAP XML format, so this automatically creates the soap:Envelope
     // as the root element and creates empty soap:Header and soap:Body
     // elements as children.
     WS_CreateResponse (gHandle, outHandle)
  
     // Navigate into soap:Body element 
     WS_EnterElement ( outHandle, "soap:Body", 1, rc )
     
     // Create a child under soap:Body
     WS_CreateElement(outHandle,"tns:ShowOrderResponse", rc)
     WS_EnterElement( outHandle, "tns:ShowOrderResponse", rc )
     
     WS_SetElement( outHandle, "tns:Result", 1, "OK", rc ) 
     
     // Send the response message
     WS_SendResponse( outHandle )
     
     WS_Cleanup( gHandle )
     WS_Cleanup( outHandle ) 
   
  

  WS_CreateElement / CreateWSElement

    WS_CreateElement ( Handle, ElementName*, outReturnCodeUV )
  

  This command creates a new, empty XML element under the current node. This is used to construct either a web service request or response XML message.

  Handle	User variable that must contain the handle of the web service request/response.
  ElementName*	XML element name. This SHOULD have an XML namespace prefix such as "tns:" (i.e. "The Name Space"), as in "tns:MyElement". The "tns:" prefix refers to the default namespace set for the web service in the web services table. Other XML namespace prefixes typically used are "soap:", etc. This name may be passed via a user variable or as a literal string.
  outReturnCodeUV	User variable in which the result code of the request is returned. The return code can be: 0: No error 14: Handle is not valid -1: Non-specific error. This error usually occurs because the XML namespace prefix could not be matched, a namespace should not be used/should have been used, or the element name occurrence index could not be found under the current node. The LAST_ERROR data part is also set to this result code.

  Example:
    Declare( ReqHandle )      // Handle to created request
    Declare( RespHandle )     // Handle to received response
    Declare( RC )             // Return code
    Declare( NewOrder )       // New Order number created
    
    // Create an outgoing web service request.  The web services table
    // defines "CreateOrder" as having a SOAP (XML) request format.
    // This 'Create' will create the soap:Header and soap:Body elements
    // inside the soap:Envelope element of the XML. 
    // The soap:Envelope element is automatically selected as the current node.
    WS_CreateRequest( ReqHandle, "CreateOrder", RC )
    If( RC #<> 0 )
    {
       Log_Error( "Could not create web request", ERROR )
       Return()
    }
    
    // Make the soap:Body element current
    WS_EnterElement( ReqHandle, "soap:Body", RC ) 
    
    // Create the tns:CreateOrder element in the current node (which is soap:Body)
    WS_CreateElement( ReqHandle,"tns:CreateOrder", RC)
    
    // Make tns:CreateOrder the current node
    WS_EnterElement( ReqHandle, "tns:CreateOrder", RC ) 
    
    // Create and set the tns:LineNumber element inside tns:CreateOrder
    WS_SetElement( ReqHandle, "tns:LineNumber", "1.00", RC  
    
    //... Continue to create and set other elements ...
    
    // Send the request and wait up to 40s for the reply
    WS_SendRequest( ReqHandle, "http://localhost/TCWS/CreateOrder.tcws", RC, RespHandle, 40 )
    
    If( RC #== 0 )
    {
        // Enter soap:Body
        WS_EnterElement( RespHandle, "soap:Body", RC )
        
        // Get the order number from the response
        WS_GetElement( RespHandle, "tns:Order", 1, NewOrder, RC )
        
        ...
    }
   
  

  WS_CreateRequest / CreateWSRequest

    WS_CreateRequest( outHandle, WebServiceName, outRC )
  

  This command creates a new, outgoing web service request that will be sent to a service provider endpoint.

  outHandle	User variable in which the handle of the created request is returned
  WebServiceName*	Local reference name for the web service. This name must exist in a row of the TC web services meta data table. This name may be passed via a user variable or as a literal string
  outRCUV	User variable in which the result code of the request is returned. The return code can be: 0: No error 1: Null/empty web service names provided as parameter 2: Error getting web service information from Web service table. This can be because the service name does not have a row in the table (case-sensitive selection), the table does not exist, or the table is mis-configured in tc2.exe.config and/or web.config (table name, schema, connection string) -1: Unknown error The LAST_ERROR data part is also set to this result code.

  Example:
    Declare( ReqHandle )      // Handle to created request
    Declare( RespHandle )     // Handle to received response
    Declare( RC )             // Return code
    // Create an outgoing web service request
    WS_CreateRequest( ReqHandle, "TwitterXML", RC )
    If( RC #<> 0 )
    {
       Log_Error( "Could not create web request", ERROR )
       Return()
    }
    
    // WS_SendRequest (requesthandle, targetURL, returncodeUV, responseHandleUV, timeout, responseMsgUV )
    // glLarge2 is a large user variable declared elsewhere with Name_UV
    // Wait up to 4 seconds for response from Twitter
    WS_SendRequest( ReqHandle, "http://twitter.com/statuses/user_timeline.xml?id=NealHorner", RC, RespHandle, 4, glLarge2 )   
    
   
  

  WS_CreateResponse / CreateWSResponse

    WS_CreateResponse( RequestHandleUV, ResponseHandleUV )
  

  This command creates a new, outgoing web service response for use in replying to an incoming web service request that this TC session provides.

  The LAST_ERROR data part will be set to the error code returned by the web service call; 0 indicates success. Some specific errors that might be encountered with this command include:

  • 2 = (TC generated) Unable to obtain a COM object.
  • -1 = (TC generated) Unknown error.

  RequestHandleUV	User variable that must contain the handle of the web service request.
  ResponseHandleUV	User variable in which the handle of the new response is returned.

  Example:
  // Processing Scriptlet for "ShowOrder" web service
  Start_WS ("ShowOrder", gHandle)
  
     Declare (varA)
     Declare (varB)
     Declare (outHandle)
     Declare (rc)
     Declare ( OrderID )
     Declare ( OrderDate )
     
     WS_EnterElement(gHandle,"soap:Body", 1, rc)
     
     WS_EnterElement(gHandle,"tns:ShowOrder", 1, rc)
  
     WS_GetElement (gHandle, "tns:orderID", OrderID, rc)
     
     // Create a response to the received request.
     // The web service table indicates that the response is
     // in SOAP XML format, so this automatically creates the soap:Envelope
     // as the root element and creates empty soap:Header and soap:Body
     // elements as children.
     WS_CreateResponse (gHandle, outHandle)
  
     // Navigate into soap:Body element 
     WS_EnterElement ( outHandle, "soap:Body", 1, rc )
     
     // Create a child under soap:Body
     WS_CreateElement(OutHandle,"tns:ShowOrderResponse", rc)
     WS_EnterElement( outHandle, "tns:ShowOrderResponse", rc )
     
     WS_SetElement( outHandle, "tns:Result", 1, "OK", rc ) 
     
     // Send the response message
     WS_SendResponse( outHandle )
   
  

  WS_DefineNamespace

    WS_DefineNamespace ( Handle, nsURI*, nsPrefix*, outReturnCodeUV )
  

  This command defines a namespace URI and its associated short-hand prefix to be used in the context of the XML document associated with the handle.

  When creating a SOAP request or response, or an XML response to a REST request, you can alternatively use the WS_AddAttribute command.

  For setting up parsing of an incoming XML document you must use this command in order to find elements/nodes that are in a namespace.

  Handle	User variable that must contain the handle of the web service request/response.
  nsURI*	The URI of the namespace This data may be passed via a user variable or as a literal string.
  nsPrefix*	The prefix by which you will refer to the namespace This value may be passed via a user variable or as a literal string.
  outReturnCodeUV	User variable in which the result code of the request is returned. The return code can be: 0: No error 14: Handle is not valid -1: Non-specific error. This error usually occurs because the XML namespace prefix could not be matched, a namespace should not be used/should have been used, or the element name occurrence index could not be found under the current node. The LAST_ERROR data part is also set to this result code.

  Example:   
  
     WS_CreateRequest( handle,"ShowOrder", rc)   
     
     // Define the myns namespace prefix via literals
     WS_DefineNamespace (handle, "http://dcconnect.com/", "myns" ,rcns)
     
     // Define the tcns namespace prefix via user vars
     Set_UV_Kbd_Data( nsURI,  "http://www.ibm.com/tcws/" )
     Set_UV_Kbd_Data( nsPrefix, "tcns" )
     WS_DefineNamespace (handle, nsURI, nsPrefix ,rcns) 
  

  WS_DisplayExecutePopups

    WS_DisplayExecutePopups
  

  When a web service script is being executed, this command, new in version 3.1.0f, tells TC to show popups for the following web service commands when Display mode is turned on (displaying of all commands in the Execution window of the TC session):

  • WS_SendRequest / SendWSRequest
  • WS_SendResponse / SendWSResponse
  • WS_EnterElement / WS_EnterElementXPATH / EnterWSElement

  Example:
   
    WS_DisplayExecutePopups
    ...
   
    Start_WS ("ShowOrder", gHandle)
      ...
  

  WS_EnterElement / WS_EnterElementXPATH / EnterWSElement

    WS_EnterElement ( Handle, ElementName*, outReturnCodeUV )
    WS_EnterElement ( Handle, ElementName*, Occurrence*, outReturnCodeUV ) 
    WS_EnterElementXPATH ( Handle, XPATHquery*, outReturnCodeUV )
  

  This command sets an element name to be the current node for navigation (e.g. finding or creating child nodes). This is used to construct or extract from either a web service request or response XML message.

  The original name EnterWSElement is deprecated; the recommended alternative is WS_EnterElement.

  Handle	User variable that must contain the handle of the web service request/response.
  ElementName*	XML element name. This may have an XML namespace prefix such as "tns:", as in "tns:MyElement". The "tns:" prefix refers to the default namespace set for the web service in the web services table/XML document. Note that some web service reponses are simple XML with no name spacing, and thus no prefix with colon is used. Other XML namespace prefixes typically used are "soap:", etc. This name may be passed via a user variable or as a literal string.
  Occurrence*	Occurrence index of the element name. This is an optional parameter -- the default is index 1. This value may be passed via a user variable or as a literal string.
  XPATHQuery*	With the XPATH-suffixed command, specify an XPATH query to locate the element. This is the general case of a selection (specifying an element name and occurrence simply creates the XPATH query internally). This value may be passed via a user variable or as a literal string.
  outReturnCodeUV	User variable in which the result code of the request is returned. The return code can be: 0: No error 14: Handle is not valid -1: Non-specific error. This error usually occurs because the XML namespace prefix could not be matched, a namespace should not be used/should have been used, or the element name occurrence index could not be found under the current node. The LAST_ERROR data part is also set to this result code.

  Example:
    Declare( ReqHandle )      // Handle to created request
    Declare( RespHandle )     // Handle to received response
    Declare( RC )             // Return code
    Declare( NewOrder )       // New Order number created
    
    // Create an outgoing web service request.  The web services table
    // defines "CreateOrder" as having a SOAP (XML) request format.
    // This 'Create' will create the soap:Header and soap:Body elements
    // inside the soap:Envelope element of the XML. 
    // The soap:Envelope element is automatically selected as the current node.
    WS_CreateRequest( ReqHandle, "CreateOrder", RC )
    If( RC #<> 0 )
    {
       Log_Error( "Could not create web request", ERROR )
       Return()
    }
    
      // Make the soap:Header the current element
    WS_EnterElement( ReqHandle, "soap:Header", RC ) 
    
    // .. Create/set element(s) inside soap:Header
    
    // Return to parent element (soap:Envelope)
    WS_LeaveElement( ReqHandle ) 
    
    
    // Make the soap:Body element current
    WS_EnterElement( ReqHandle, "soap:Body", RC ) 
    
    // Create the tns:CreateOrder element in the current node (which is soap:Body)
    WS_CreateElement( ReqHandle,"tns:CreateOrder", RC)
    
    // Make tns:CreateOrder the current node, using XPATH query 
    WS_EnterElementXPATH( ReqHandle, "tns:CreateOrder[1]", RC ) 
    
    // Create and set the tns:LineNumber element inside tns:CreateOrder
    WS_SetElement( ReqHandle, "tns:LineNumber", "1.00", RC  
    
    //... Continue to create and set other elements ...
    
    // Send the request and wait up to 40s for the reply
    WS_SendRequest( ReqHandle, "http://localhost/TCWS/CreateOrder.tcws", RC, RespHandle, 40 )
    
    If( RC #== 0 )
    {
        // Enter soap:Body
        WS_EnterElement( RespHandle, "soap:Body", RC )
        
        // Get the order number from the response
        WS_GetElement( RespHandle, "tns:Order", 1, NewOrder, RC )
        
        ...
    }
   
  

  WS_GetAttribute

    WS_GetAttribute ( Handle, attribName*, outAttribValueUV, outReturnCodeUV )
  

  This command gets the value of a named attribute from the current node.

  Handle	User variable that must contain the handle of the web service request/response.
  attribName*	The attributes name. This name may be passed via a user variable or as a literal string.
  outAttribValueUV*	The target user variable to hold the retrieved value.
  outReturnCodeUV	User variable in which the result code of the request is returned. The return code can be: 0: No error 14: Handle is not valid -1: Non-specific error. This error usually occurs because the XML namespace prefix could not be matched, a namespace should not be used/should have been used, or the attribute name could not be found under the current node. The LAST_ERROR data part is also set to this result code.

  Example:   
         
       WS_GetAttribute( handle, "some_attribute", attribValue, rc ) 
       
  

  WS_GetElement / WS_GetElementXPATH / GetWSElement

    WS_GetElement ( Handle, ElementName*, outElementUV, outReturnCodeUV )
    WS_GetElement ( Handle, ElementName*, Occurrence*, outElementUV, outReturnCodeUV ) 
    WS_GetElementXPATH ( Handle, XPATHquery*, outElementUV, outReturnCodeUV )
  

  This command gets the value of an element in an XML document that has been received in an incoming web service request, or has been received in a response from a call to a web service endpoint.

  The original command name GetWSElement is deprecated; the recommended alternative is WS_GetElement.

  Handle	User variable that must contain the handle of the web service request/response.
  ElementName*	XML element name. This MAY have an XML namespace prefix such as "tns:", as in "tns:MyElement". The "tns:" prefix refers to the default namespace set for the web service in the web services table. Other XML namespace prefixes typically used are "soap:", etc. Note that an XML response from a web service may have no use of namespaces, so you would refer to the element without any prefix nor colon. This name may be passed via a user variable or as a literal string.
  Occurrence*	Occurrence index of the element name. This is an optional parameter -- the default is index 1. This value may be passed via a user variable or as a literal string.
  XPATHQuery*	With the XPATH-suffixed command, specify an XPATH query to locate the element. This is the general case of a selection (specifying an element name and occurrence simply creates the XPATH query internally). This value may be passed via a user variable or as a literal string.
  outElementUV*	Target user variable for the retrieved value.
  outReturnCodeUV	User variable in which the result code of the request is returned. The return code can be: 0: No error 14: Handle is not valid -1: Non-specific error. This error usually occurs because the XML namespace prefix could not be matched, a namespace should not be used/should have been used, or the element name occurrence index could not be found under the current node. The LAST_ERROR data part is also set to this result code.

  Example:
    Declare( ReqHandle )      // Handle to created request
    Declare( RespHandle )     // Handle to received response
    Declare( RC )             // Return code
    Declare( NewOrder )       // New Order number created
    
    // Create an outgoing web service request.  The web services table
    // defines "CreateOrder" as having a SOAP (XML) request format.
    // This 'Create' will create the soap:Header and soap:Body elements
    // inside the soap:Envelope element of the XML. 
    // The soap:Envelope element is automatically selected as the current node.
    WS_CreateRequest( ReqHandle, "CreateOrder", RC )
    If( RC #<> 0 )
    {
       Log_Error( "Could not create web request", ERROR )
       Return()
    }
    
    // Make the soap:Body element current
    WS_EnterElement( ReqHandle, "soap:Body", RC ) 
    
    // Create the tns:CreateOrder element in the current node (which is soap:Body)
    WS_CreateElement( ReqHandle,"tns:CreateOrder", RC)
    
    // Make tns:CreateOrder the current node
    WS_EnterElement( ReqHandle, "tns:CreateOrder", RC ) 
    
    // Create and set the tns:LineNumber element inside tns:CreateOrder
    WS_SetElement( ReqHandle, "tns:LineNumber", "1.00", RC  
    
    //... Continue to create and set other elements ...
    
    // Send the request and wait up to 40s for the reply
    WS_SendRequest( ReqHandle, "http://localhost/TCWS/CreateOrder.tcws", RC, RespHandle, 40 )
    
    If( RC #== 0 )
    {
        // Enter soap:Body
        WS_EnterElement( RespHandle, "soap:Body", RC )
        
        // Get the order number from the response
        WS_GetElement( RespHandle, "tns:Order", 1, NewOrder, RC )  
        
        // Get it via XPATH as alternative method
        // Get the order number from the response
        WS_GetElementXPATH( RespHandle, "tns:Order[1]", NewOrder, RC )
        
        ...
    }
   
  

  WS_GetLastErrorText

    WS_GetLastErrorText ( outTextUV )
  

  This command gets the text of the last error that occurred with any of the Web Service commands (WS_xxxx). If the last command did not have an error, then the target UV is simply cleared. Even Web Service commands that don't have a return code variable as a parameter, could generate error text that can be retrieved, if those commands have an error.

  outTextUV

  Target user variable for the retrieved error text.

  Example:
    Declare( ReqHandle )      // Handle to created request
    Declare( RC )             // Return code
    Declare( ErrorText )      // Text of error if one occurs
    
    // Create an outgoing web service request.  The web services table
    // defines "CreateOrder" as having a SOAP (XML) request format.
    // This 'Create' will create the soap:Header and soap:Body elements
    // inside the soap:Envelope element of the XML. 
    // The soap:Envelope element is automatically selected as the current node.
    WS_CreateRequest( ReqHandle, "CreateOrder", RC )
    If( RC #<> 0 )
    {
       WS_GetLastError ( ErrorText )
       Log_Error( "Could not create web request, error is:", ERROR )
       Log_Error( ErrorText, ERROR )
       Return()
    }
    
  

  WS_LeaveElement / LeaveWSElement

    WS_LeaveElement ( Handle )
  

  This command leaves the current node and moves up to the parent node to be the current node for navigation (e.g. finding or creating child nodes). If there is no parent then there is no effect and no error. This is used to construct or extract from either a web service request or response XML message.

  The LAST_ERROR data part will be set to the error code returned by the web service call; 0 indicates success. Some specific errors that might be encountered with this command include:

  • 2 = (TC generated) Unable to obtain a COM object.
  • -1 = (TC generated) Unknown error.

  Handle

  User variable that must contain the handle of the web service request/response.

  Example:
    Declare( ReqHandle )      // Handle to created request
    Declare( RespHandle )     // Handle to received response
    Declare( RC )             // Return code
    Declare( NewOrder )       // New Order number created
    
    // Create an outgoing web service request.  The web services table
    // defines "CreateOrder" as having a SOAP (XML) request format.
    // This 'Create' will create the soap:Header and soap:Body elements
    // inside the soap:Envelope element of the XML. 
    // The soap:Envelope element is automatically selected as the current node.
    WS_CreateRequest( ReqHandle, "CreateOrder", RC )
    If( RC #<> 0 )
    {
       Log_Error( "Could not create web request", ERROR )
       Return()
    }
    
    // Make the soap:Header the current element
    WS_EnterElement( ReqHandle, "soap:Header", RC ) 
    
    // .. Create/set element(s) inside soap:Header
    
    // Return to parent element (soap:Envelope)
    WS_LeaveElement( ReqHandle ) 
    
    // Make the soap:Body element current
    WS_EnterElement( ReqHandle, "soap:Body", RC ) 
    
    // Create the tns:CreateOrder element in the current node (which is soap:Body)
    WS_CreateElement( ReqHandle,"tns:CreateOrder", RC)
    
    // Make tns:CreateOrder the current node
    WS_EnterElement( ReqHandle, "tns:CreateOrder", RC ) 
    
    // Create and set the tns:LineNumber element inside tns:CreateOrder
    WS_SetElement( ReqHandle, "tns:LineNumber", "1.00", RC  
    
    //... Continue to create and set other elements ...
    
    // Send the request and wait up to 40s for the reply
    WS_SendRequest( ReqHandle, "http://localhost/TCWS/CreateOrder.tcws", RC, RespHandle, 40 )
    
    If( RC #== 0 )
    {
        // Enter soap:Body
        WS_EnterElement( RespHandle, "soap:Body", RC )
        
        // Get the order number from the response
        WS_GetElement( RespHandle, "tns:Order", 1, NewOrder, RC )
        
        ...
    }
   
  

  WS_NamespacePop

    WS_NamespacePop ( Handle, outReturnCodeUV )
  

  The XML namespace manager used to create and parse web service XML documents tracks the namespaces and associated prefixes on a level-by-level basis. If your main routine defines name spaces at its level, but then calls a common routine that adds its own content to the XML document, it would take coordination between TC script code modules to prevent accidental redefinition of some namespace prefix to some other namespace URI value. This command facilitates having code modules that contribute to an XML document without need to have any coordination on what prefixes are being used for what URI. Use this command to 'pop' the saved (pushed) level off of the internal namespace manager's stack so that namespace prefixes are restored to their set-up prior to whatever namespace settings were done in a routine.

  Handle

  User variable that must contain the handle of the web service request/response.

  outReturnCodeUV

  User variable in which the result code of the request is returned. The return code can be: 0: No error 14: Handle is not valid -1: Non-specific error. This error usually occurs because the XML namespace prefix could not be matched, a namespace should not be used/should have been used, or the element name occurrence index could not be found under the current node. The LAST_ERROR data part is also set to this result code.

  Example:   
  
     WS_CreateRequest( handle,"ShowOrder", rc)   
     
     // Define the myns namespace prefix via literals
     WS_DefineNamespace (handle, "http://dcconnect.com/", "myns" ,rcns)
     
     WS_CreateElement ( handle,  "myns:shipment", rc ) 
                                        
     // Add return address data to the XML document                                      
     Call CreateReturnAddress( handle ) 
     
      
     WS_CreateElement(  handle, "myns:consignee", rc ) 
     
     ...
     
    // Add a return address element to the document 
    // This puts the return address in namespace "http://ibm.com/addressdata/".
    // It pushes and pops the namespace manager stack so it can use the prefix 
    // "myns" without fear of overwriting the caller's namespace setup. 
    Sub CreateReturnAddress( inDocHandle ) 
    
        // Push namespace level before we do our work   
        WS_NamespacePush( inDocHandle, rc )  
        // Note:  See example in WS_NamespacePush 
        // for how to make more compact XML by defining the namespace at the head node level.
        WS_DefineNamespace (inDocHandle, "http://ibm.com/addressdata/", "myns" ,rcns) 
        WS_CreateElement ( inDocHandle,  "myns:returnaddr", rc ) 
        ... Populate the the element 
        // Pop the namespace manager back to the state it was in when we were called
        WS_NamespacePop( inDocHandle, rc )      
        
    EndSub()
   
  

  WS_NamespacePush

    WS_NamespacePush ( Handle, outReturnCodeUV )
  

  The XML namespace manager used to create and parse web service XML documents tracks the namespaces and associated prefixes on a level-by-level basis. If your main routine defines name spaces at its level, but then calls a common routine that adds its own content to the XML document, it would take coordination between TC script code modules to prevent accidental redefinition of some namespace prefix to some other namespace URI value. This command facilitates having code modules that contribute to an XML document without need to have any coordination on what prefixes are being used for what URI. Use this command to 'push' the current level onto the internal namespace manager's stack so that namespace prefixes may be defined without fear of overwriting a calling routine's namespace data.

  Handle

  User variable that must contain the handle of the web service request/response.

  outReturnCodeUV

  User variable in which the result code of the request is returned. The return code can be: 0: No error 14: Handle is not valid -1: Non-specific error. This error usually occurs because the XML namespace prefix could not be matched, a namespace should not be used/should have been used, or the element name occurrence index could not be found under the current node. The LAST_ERROR data part is also set to this result code.

  Example:   
  
     WS_CreateRequest( handle,"ShowOrder", rc)   
     
     // Define the myns namespace prefix via literals
     WS_DefineNamespace (handle, "http://dcconnect.com/", "myns" ,rcns)
     
     WS_CreateElement ( handle,  "myns:shipment", rc ) 
                                        
     // Add return address data to the XML document                                      
     Call CreateReturnAddress( handle ) 
     
      
     WS_CreateElement(  handle, "myns:consignee", rc ) 
     
     ...
     
    // Add a return address element to the document 
    // This puts the return address in namespace "http://ibm.com/addressdata/".
    // It pushes and pops the namespace manager stack so it can use the prefix 
    // "myns" without fear of overwriting the caller's namespace setup. 
    Sub CreateReturnAddress( inDocHandle )    
    
        // Push namespace level before we do our work   
        WS_NamespacePush( inDocHandle, rc )  
            // Create returnaddr node/element in "http://ibm.com/addressdata/" namespace
            WS_CreateElement ( inDocHandle,  "myns:returnaddr", rc ) 
            WS_EnterElementXPATH( inDocHandle, "myns:returnaddr", rc ) 
                // This establishes the namespace locally for myns prefix 
                WS_AddAttribute( inhandle, "xmlns:myns", "http://ibm.com/addressdata/", rc )     
                ... Populate the the element 
                 
            WS_LeaveElement( inDocHandle ) 
        // Pop the namespace manager back to the state it was in when we were called 
        WS_NamespacePop( inDocHandle, rc )     
    EndSub()
   
  

  WS_SendRequest / SendWSRequest

    WS_SendRequest( ReqHandle, TargetURI*, outRCUV, outResponseHandleUV, Timeout* )
    WS_SendRequest( ReqHandle, TargetURI*, outRCUV, outResponseHandleUV, Timeout*, outResponseMsgUV )
  

  This command sends an outgoing web service request to a service provider endpoint.

  ReqHandle	User variable in which the handle of the request is provided (The handle created by WS_CreateRequest )
  TargetURI*	Uniform resource identifier (URI) for the web service. This always starts with "http://...". For a REST web service, this may include query string data. This URI may be passed via a user variable or as a literal string.
  outRCUV	User variable in which the result code of the request is returned. The return code can be: 0: No error 5: Problem sending request. This may be an issue such as receiving an HTTP 500 response. The outResponseMsgUV can be used to obtain some error information. 6: Timeout waiting for response 9: Invalid SOAP action header (obtained from web service table for service name) 12: Invalid target URL 14: Request handle value did not represent a valid WS request -1: Unknown error The LAST_ERROR data part is also set to this result code.
  outResponseHandleUV	Target user variable for handle to the response returned from the web service. This handle would be used in commands such as WS_EnterElement.
  Timeout*	How many seconds to wait for a response from the web service provider. This values may be passed via a user variable or as a literal string.
  outResponseMsgUV	Optional target user variable for return of the actual response text from the web service. Note that only non-XML responses (e.g. JSON, HTML ) are copied into this variable. Text explaining an exception/problem may also be provided (in that case, the return code value will be non-zero).

  Example:
    Declare( ReqHandle )      // Handle to created request
    Declare( RespHandle )     // Handle to received response
    Declare( RC )             // Return code
    // Create an outgoing web service request
    WS_CreateRequest( ReqHandle, "TwitterXML", RC )
    If( RC #<> 0 )
    {
       Log_Error( "Could not create web request", ERROR )
       Return()
    }
    
    // WS_SendRequest (requesthandle, targetURL, returncodeUV, responseHandleUV, timeout, responseMsgUV )
    // glLarge2 is a large user variable declared elsewhere with Name_UV
    // Wait up to 4 seconds for response from Twitter
    WS_SendRequest( ReqHandle, "http://twitter.com/statuses/user_timeline.xml?id=NealHorner", RC, RespHandle, 4, glLarge2 )   
    
   
  

  WS_SendResponse / SendWSResponse

    WS_SendResponse( ResponseHandle )
    WS_SendResponse( ResponseHandle, MessageText* )
  

  This command sends an outgoing web service response as a reply to an incoming web service request.

  The LAST_ERROR data part will be set to the error code returned by the web service call; 0 indicates success. Some specific errors that might be encountered with this command include:

  • 2 = (TC generated) Unable to obtain a COM object.
  • -1 = (TC generated) Unknown error.

  ResponseHandle	User variable that must contain the handle of the web service response - returned by WS_CreateResponse.
  MessageText*	Optional user variable or literal string containing the message to be returned. This would be used if the response is plain text, HTML, or a JSON string (instead of XML).

  Example:
  // Processing Scriptlet for "ShowOrder" web service
  Start_WS ("ShowOrder", gHandle)
  
     Declare (varA)
     Declare (varB)
     Declare (outHandle)
     Declare (rc)
     Declare ( OrderID )
     Declare ( OrderDate )
     
     WS_EnterElement(gHandle,"soap:Body", 1, rc)
     
     WS_EnterElement(gHandle,"tns:ShowOrder", 1, rc)
  
     WS_GetElement (gHandle, "tns:orderID", OrderID, rc)
     
     // Create a response to the received request.
     // The web service table indicates that the response is
     // in SOAP XML format, so this automatically creates the soap:Envelope
     // as the root element and creates empty soap:Header and soap:Body
     // elements as children.
     WS_CreateResponse (gHandle, outHandle)
  
     // Navigate into soap:Body element 
     WS_EnterElement ( outHandle, "soap:Body", 1, rc )
     
     // Create a child under soap:Body
     WS_CreateElement(OutHandle,"tns:ShowOrderResponse", rc)
     WS_EnterElement( outHandle, "tns:ShowOrderResponse", rc )
     
     WS_SetElement( outHandle, "tns:Result", 1, "OK", rc ) 
     
     // Send the response message
     WS_SendResponse( outHandle )
   
  

  WS_SetElement / WS_SetElementXPATH / SetWSElement

    WS_SetElement      ( Handle, ElementName*, ElementValue*, outReturnCodeUV )
    WS_SetElement      ( Handle, ElementName*, Occurrence*, ElementValue*, outReturnCodeUV )  
    WS_SetElementXPATH ( Handle, XPATHquery*, ElementValue*, outReturnCodeUV )
  

  This command sets the value of an element in an XML document that is being created for transmission to a web service endpoint. For the non-XPATH versions of the command ONLY, if the element / element occurrence is not found then it is created under the current XML node.

  Handle	User variable that must contain the handle of the web service request/response.
  ElementName*	XML element name. This should have an XML namespace prefix such as "tns:", as in "tns:MyElement". The "tns:" prefix refers to the default namespace set for the web service in the web services table. Other XML namespace prefixes typically used are "soap:", etc. This name may be passed via a user variable or as a literal string.
  Occurrence*	Occurrence index of the element name. This is an optional parameter -- the default is index 1. This value may be passed via a user variable or as a literal string.
  XPATHQuery*	With the XPATH-suffixed command, specify an XPATH query to locate the element. This is the general case of a selection (specifying an element name and occurrence simply creates the XPATH query internally). This value may be passed via a user variable or as a literal string. Note: When using XPATH, a non-existent node/element WILL NOT be created for you.
  ElementValue*	Value to be set for the element. This value may be passed via a user variable or as a literal string (including a string version of a number).
  outReturnCodeUV	User variable in which the result code of the request is returned. The return code can be: 0: No error -1: Non-specific error. This error usually occurs because the XML namespace prefix could not be matched. The LAST_ERROR data part is also set to this result code.

  Example:
    Declare( ReqHandle )      // Handle to created request
    Declare( RespHandle )     // Handle to received response
    Declare( RC )             // Return code 
    Declare( LineNum ) 
    
    // Create an outgoing web service request.  The web services table
    // defines "CreateOrder" as having a SOAP (XML) request format.
    // This 'Create' will create the soap:Header and soap:Body elements
    // inside the soap:Envelope element of the XML. 
    // The soap:Envelope element is automatically selected as the current node.
    WS_CreateRequest( ReqHandle, "CreateOrder", RC )
    If( RC #<> 0 )
    {
       Log_Error( "Could not create web request", ERROR )
       Return()
    }
    
    // Make the soap:Body element current
    WS_EnterElement( ReqHandle, "soap:Body", RC ) 
    
    // Create the tns:CreateOrder element in the current node (which is soap:Body)
    WS_CreateElement( ReqHandle,"tns:CreateOrder", RC)
    
    // Make tns:CreateOrder the current node
    WS_EnterElement( ReqHandle, "tns:CreateOrder", RC ) 
    
    UV_Math( LineNum, =, 1, 0.2 ) 
    
    // Create and set the tns:LineNumber element inside tns:CreateOrder
    WS_SetElement( ReqHandle, "tns:LineNumber", LineNum, RC  
    
    //... Continue to create and set other elements ...
    
    UV_Math( LineNum, +, 1, 0.2 ) 
    
    //... Create, then set using XPATH to find the last element of that name in the node
    WS_CreateElement( ReqHandle,"tns:LineNumber", RC)  
    WS_SetElementXPATH( ReqHandle, "(tns:LineNumber)[last()]", RC  
    
    // Send the request and wait up to 40s for the reply
    WS_SendRequest( ReqHandle, "http://localhost/TCWS/CreateOrder.tcws", RC, RespHandle, 40 )
   
  

  WS_SetHTTPBody

    WS_SetHTTPBody ( Handle, Body* )
  

  Use this command to set the HTTP body of the current web service request if it is required and it is not an XML document - such as for JSON formatted requests. For XML documents use the commands for building the XML document: WS_CreateElement / CreateWSElement, WS_EnterElement / WS_EnterElementXPATH / EnterWSElement, WS_LeaveElement / LeaveWSElement, WS_SetElement / WS_SetElementXPATH / SetWSElement, ....

  Note that when building a JSON formatted body which will often contain double quotes, colons and possibly forward slashes and other special characters, it can be helpful to use the Begin_UV / End_UV command to layout the format of the JSON content and use pre-defined variables for the various special characters. The example below uses this technique.

  Handle	User variable that must contain the handle of the web service request.
  *Body	The user variable containing content to be set in the body of the web service request.

  Example:
   
    Declare( ReqHandle )      // Handle to created request
    Declare( RespHandle )     // Handle to received response
    Declare( RC )             // Return code 
  
    Declare ( uvlUID )
    Declare ( uvlPW )
    Declare ( uvlColon )
    Declare ( uvlFSlash )
    Declare ( uvlJSONBody )
    Declare ( uvlURL )
  
    // Initialize the character variables  
    Set_UV_Kbd_Data ( uvlColon, ":" )
    Set_UV_Kbd_Data ( uvlFSlash, "/" )
  
    // Create an outgoing GetToken web service request with a JSON formatted body.  A token is returned 
    // if valid credentials are provided.
    WS_CreateRequest( ReqHandle, "GetToken", RC )
    If( RC #<> 0 )
    {
       Log_Error( "Could not create web request", ERROR )
       Return()
    }
  
    // Request token, passing in the user ID and PW in JSON format 
  
    Set_UV_Kbd_Data ( uvlUID, "UserDean" )
    Set_UV_Kbd_Data ( uvlPW,  "PWDean1!" )
  
    Begin_UV()
      {"username":uvlColon(X)":uvlUID(X)","password":uvlColon(X)":uvlPW(X)"}
    End_UV ( uvlJSONBody )
  
    WS_SetHTTPParameter(ReqHandle, "Content_Type",  "application/json" )
    WS_SetHTTPParameter(ReqHandle, "Response_Type", "application/json" )
    WS_SetHTTPParameter(ReqHandle, "Method",        "POST" )
  
    WS_SetHTTPBody     (ReqHandle, uvlJSONBody )
  
    Begin_UV()
      http:uvlColon(X):uvlFSlash(X):uvlFSlash(X)testws.ibm.com:uvlColon(X):8154(X):uvlFSlash(X)data-service:uvlFSlash(X)login
    End_UV ( uvlURL )
    
    // Send the request and wait up to 40s for the reply
    WS_SendRequest( ReqHandle, uvlURL, RC, RespHandle, 40 )
   
  

  WS_SetHTTPParameter

    WS_SetHTTPParameter ( Handle, ParameterName*, ParameterValue* )
  

  Use this command to set one of the pre-defined HTTP request header parameters. These include:

  • ACCEPT
  • CONTENT_TYPE
  • METHOD
  • RESPONSE_TYPE

  The following describes the default value of each of these pre-defined HTTP parameters if they are not explicitly defined by the WS_SetHTTPParameter command:

  • ACCEPT: If RESPONSE_TYPE is SOAPXML or XML then ACCEPT is set to text/xml. Otherwise it is set to text/plain.
  • CONTENT_TYPE: If METHOD is PUT or POST then the CONTENT_TYPE is set to text/xml;charset="utf-8". Otherwise the default is null.
  • METHOD: The default value of METHOD comes from the Web Service definition (See the Method parameter in the Web Services Setup for information about defining web services).
  • RESPONSE_TYPE: The default value of RESPONSE_TYPE comes from the Web Service definition (See the ResponseType parameter in the Web Services Setup for information about defining web services).

  UV_Handle	User variable that must contain the handle of the web service request.
  ParameterName*	The name of the request parameter. This name may be passed via a user variable or as a literal string.
  ParameterValue*	The value to be assigned to the specified request parameter. This value may be passed via a user variable or as a literal string.

  Example:
   
    Declare( ReqHandle )      // Handle to created request
    Declare( RespHandle )     // Handle to received response
    Declare( RC )             // Return code 
  
    Declare ( uvlUID )
    Declare ( uvlPW )
    Declare ( uvlColon )
    Declare ( uvlFSlash )
    Declare ( uvlJSONBody )
    Declare ( uvlHeaderValue )
    Declare ( uvlParameterValue )
    Declare ( uvlURL )
  
    // Initialize the character variables  
    Set_UV_Kbd_Data ( uvlColon, ":" )
    Set_UV_Kbd_Data ( uvlFSlash, "/" )
  
    // Create an outgoing GetToken web service request with a JSON formatted body.  A token is returned 
    // if valid credentials are provided.
    WS_CreateRequest( ReqHandle, "CreateOrder", RC )
    If( RC #<> 0 )
    {
       Log_Error( "Could not create web request", ERROR )
       Return()
    }
  
    // Request token, passing in the user ID and PW in JSON format 
  
    Set_UV_Kbd_Data ( uvlUID, "UserDean" )
    Set_UV_Kbd_Data ( uvlPW,  "PWDean1!" )
  
    Begin_UV()
      {"username":uvlColon(X)":uvlUID(X)","password":uvlColon(X)":uvlPW(X)"}
    End_UV ( uvlJSONBody )
  
    Set_UV_Kbd_Data ( uvlParameterValue, "application/json" )
    WS_SetHTTPParameter(ReqHandle, "Content_Type", uvlParameterValue )
  
    Set_UV_Kbd_Data ( uvlParameterValue, "application/json" )
    WS_SetHTTPParameter(ReqHandle, "Response_Type", uvlParameterValue )
  
    Set_UV_Kbd_Data ( uvlParameterValue, "POST" )
    WS_SetHTTPParameter(ReqHandle, "Method", uvlParameterValue )
  
    WS_SetHTTPBody     (ReqHandle, uvlJSONBody )
  
    Begin_UV()
      http:uvlColon(X):uvlFSlash(X):uvlFSlash(X)testws.ibm.com:uvlColon(X):8154(X):uvlFSlash(X)data-service:uvlFSlash(X)login
    End_UV ( uvlURL )
    
    // Send the request and wait up to 40s for the reply
    WS_SendRequest( ReqHandle, uvlURL, RC, RespHandle, 40 )
   
  

  WS_ToFile

    WS_ToFile ( UV_Handle, FILENAME     [, RC_UV ] )
    WS_ToFile ( UV_Handle, FILENAME.EXT [, RC_UV ] )
    WS_ToFile ( UV_Handle, FILE_UV      [, RC_UV ] )
  

  The operation of this command is similar to the Log_Data command with the following differences:

  • The source is a handle to a web service message which will be 'serialized' into a string and then written to the specified file. The handle can be associated with any of these documents:
    1. SOAP request or response your script has built
    2. XML response you have built as the response to a REST request
    3. SOAP incoming request
    4. REST incoming request presented as an XML document for data extraction purposes
    This command will output the string "WSToString is only valid for requests/responses where an XML document is involved" if used with a REST request that you have built, or with a JSON/TEXT/HTML reply you have built.
  • The MODE parameter is not available for WS_ToFile; all file operations are OVERWRITE.

  Please see Log_Data for more information, including more information about the second and third parameters below.

  UV_Handle	A user variable which contains the handle for the web service request / response containing an XML message.
  FILENAME, FILENAME.EXT, or FILE_UV	The file name for the data file. The filename parameter may contain one or more environment variables which are denoted by their starting and ending percent signs (%). TC will resolve these environment variables at compile time.
  RC_UV	This is the optional return code user variable.

  Example:
   
      // Write the request/response to file
      WS_ToFile(handle, "c:\Response.XML", uvRC)
   
  

  WS_ToString

    WS_ToString ( UV_Handle, UV_Target )
  

  This command will serialiize the web service request/response object into a string in a user variable.

  UV_Handle

  A user variable which contains the handle for the web service message. The handle can be associated with any of these documents: SOAP request or response your script has built XML response you have built as the response to a REST request SOAP incoming request REST incoming request presented as an XML document for data extraction purposes This command will output the string "WSToString is only valid for requests/responses where an XML document is involved" if used with a REST request that you have built, or with a JSON/TEXT/HTML reply you have built.

  UV_Target

  The target user variable in which to store the string that represents the serialized XML message.

  If the specified UV_Target is not large enough for the XML string, the string will be stored up to the length of the user variable and a message will be logged indicating that truncation occurred; in addition the LAST_ERROR data part will be set to -6.

  Example:
  
      Name_UV(UV1,   uvRC)
      Name_UV(NEX_UV,   RespHandle)
  
      Name_UV(UV250, uvSerializedMessage)
  
      ...
     
      // Send outgoing message and wait for response      
      ...
     
      // Convert the response message to a string
      WS_ToString(RespHandle, uvSerializedMessage)
   
  

  Xact_Age

    Xact_Age( LABEL, AGE_SECONDS* )
  

  Xact_Age calculates the difference in seconds between the current time at the personal computer and the timestamp of the transaction record, and causes a branch to the label if the time limit specified is exceeded.

  This command is intended to allow you to avoid performing resource-consuming processing and communications in handling a query and reporting results based on a request in a stale transaction. If heavy usage of the system, an outage of the database machine, or other such event that can cause long delays in getting to process a transaction occurs, there is often no reason to consume resources responding to a terminal or operator who has long since stopped waiting for an answer.

  Note that you can also get the numeric value of the transaction age using the XACT_AGE data part with any script command which uses a named data part.

  As of October 2004, the new command, Use_Adjusted_Xact_Time, can be used to tell TC to get calculate the transaction's age using the adjusted date and time fields from the transaction record rather than the terminal date and time fields. When you have terminals that are in different time zones from the server, the terminal date and time fields of the transaction record will contain the date and time of the terminal's time zone; but the adjusted date and time fields will contain the terminal's date and time adjusted to the server's time zone. This is necessary when calculating transaction age because the age is always relative to the server time. For more details, please see Use_Adjusted_Xact_Time.

  You can specify the AGE_SECONDS parameter to be a few seconds less than the time-out parameter the data collection terminal is using. (This can be the host communications timeout value specified in the terminal configuration file, or a timeout coded into a CFR on the terminal, or perhaps just the maximum amount of time you might expect the operator to wait around at the terminal for an answer to a query.)

  Due to a lack of timestamp data on incoming remote validation and data requests, this command is not available when TC is used in REMOTE_VALIDATION or DATA_REQUEST mode.

  Note: Parameters marked with a * can be specified either as a constant value (for example, 1, 15, "ShippingMailbox", and so forth) or as the current value of a TC user variable by using the user variable's name or the notation UVn, where n ranges from 1 to 250 or the maximum defined by Define_UVs.

  LABEL	Branch to this label if the transaction exceeds the age limit. If the text is the name of a subroutine, the subroutine is called instead of a Goto being used, and control will return to the next command when the subroutine ends.
  AGE_SECONDS*	The age limit, given in seconds, for normal processing of the transaction.

  Example:
   
    // Don't bother doing a query if it is older than 45 seconds.
    Xact_Age( Do_not_bother, 45 )
   
    // ...
    // Do query here
    // Process transaction here
    // ...
   
  Do_not_bother:
   
  

  XML_AddAttribute

    XML_AddAttribute( UV, Attribute_name*, Attribute_value*  )
  

  XML_AddAttribute adds an attribute to the current element. Because the XML_CreateElement command only allows you to specify a single attribute, it is necessary to use this XML_AddAttribute command to add additional attributes to the newly created element.

  Note that at this time, the XML_AddAttribute cannot be used to add an attribute to a field created by the XML_AddField command.

  All parameters, except the first user variable, can be specified as a quoted string, a user variable, or a data part.

  UV	A user variable which contains the handle for the XML message. It was returned by a previous call to XML_Create, XML_CreateBOD, XML_Send, XML_SendBOD, or XML_Parse
  Attribute_name*	The case sensitive name of the attribute which should be set in the element. This is an optional field for this command. If Attribute_value is set and Attribute_name is not set, the Attribute_name will default to 'qualifier'.
  Attribute_value*	The value of the attribute which should be set in the element. This is not an optional field for this command.

  Examples:
   
    // First create the soapenv:Envelope element with the initial xmlns attribute for soapenv
    XML_CreateElement(uvSoapMsg, "soapenv:Envelope", "xmlns:soapenv", "http://schemas.xmlsoap.org/soap/envelope/")
  
    // Then add two more xmlns attributes for this same soapenv:Envelope element of the soap message
    XML_AddAttribute(uvSoapMsg, "xmlns:pts", "http://CommonObjects/PTS")
    XML_AddAttribute(uvSoapMsg, "xmlns:tnt", "http://com/ibm/swg/iss/tnt/")
  
    // The resulting XML element will look like:
    // <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pts="http://CommonObjects/PTS" xmlns:tnt="http://com/ibm/swg/iss/tnt/">
  
  

  XML_AddField

    XML_AddField( UV, Field_name* [ [, Attribute_name*], Attribute_value*], Data* )
  

  XML_AddField creates a new element with the name and attribute specified in the call and sets the new element's data to the value provided. Except for creating a new element, it is the same as XML_SetField The current element is not changed by this call.

  All fields, except the first user variable, can be specified as a quoted string, a user variable, or a data part.

  UV	A user variable which contains the handle for the XML message. It was returned by a previous call to XML_Create, XML_CreateBOD, XML_Send, XML_SendBOD, or XML_Parse
  Field_name*	The name of the element which should be created. Field names are case sensitive.
  Attribute_name*	The case sensitive name of the attribute which should be set in the element. This is an optional field. If Attribute_value is set and Attribute_name is not set, it will default to 'index'.
  Attribute_value*	The value of the attribute which should be set in the element. This is an optional field.
  Data*	The value to be set in the element.

  Examples:
   
    // Add a new SYNCIND node under the current
    // position and set the data in the node to "Y"
    XML_AddField (UV1, "SYNCIND", "Y")
   
    // Add a SITELEVEL field with attribute 'index' and attribute value '1'
    // and set the value to 'M30'
    XML_AddField (UV1, "SITELEVEL", "1", "M30")
   
    // or
    XML_AddField (UV1, "SITELEVEL", "index", "1", "M30")
  

  XML_Cleanup

    XML_Cleanup( UV )
  

  XML_Cleanup frees any storage associated with the provided handle. It then makes the handle available for future XML messages. Each successful XML_Create, XML_CreateBOD, XML_Send, and XML_SendBOD, and XML_Parse command should have an XML_Cleanup command to free the associated storage. If that is not done, eventually TC will run out of handles, and no more XML messages can be processed.

  UV	A user variable which contains the handle for the XML message. It was returned by a previous call to XML_Create, XML_CreateBOD, XML_Send, XML_SendBOD, or XML_Parse

  Example:
   
      // Create a SYNC LOGON BOD
      XML_CreateBOD (UV1, "sync_logon_001.dtd")
   
      // Send the BOD
      XML_SendBOD (UV1, UV2, 60, Label1)
   
      // Cleanup the XML message
      XML_Cleanup (UV1)
   
      // Do something with the return message
   
      // Cleanup the returned message
      XML_Cleanup (UV2)
   
      // Skip the error label part
      Goto Label2
   
    Label1:
      // Cleanup the XML message
      XML_Cleanup (UV1)
   
    Label2:
  

  XML_Configure

    XML_Configure( Configuration string* )
  

  XML_Configure is used to provide dynamic configuration information to a user supplied function for sending XML messages to other applications (see XML_Sender for information on setting up and configuring a custom XML message sending function.)

  Configuration string*

  A user variable, quoted string, or data part containing configuration information for the function specified in XML_Sender. The format of this string is dependent on the implementation of the function used to send XML messages. However, a recommended method is to provide a key / value pair of the format "Key=Value".

  There is one configuration string which the default XML message handler in TC understands. It is "FileName = value" where value is any valid file name. This configuration command should be used to set the file where TC outputs XML messages. By default, TC outputs XML messages to the file "TC.XML".

  Note: The following information is provided for sophisticated users who need to write their own configuration function. The capabilities provided by TC and the ERP transaction script library.

  If configuration information is required, the user should provide a second function in the dynamic link library specified by XML_Sender. That function should have the following prototype

    int __cdecl XMLConfigure (const char *ConfigString);
  

  where ConfigString is a string containing configuration information for the function used to send XML messages. The format of the string must be determined by the implementor of the XML message send function, and should be provided to the TC script writer.

  If the function is not found in the DLL and XML_Configure is used in the TC script, an error will be generated when TC starts.

  When TC is communicating with an ERP adapter, these are the configuration strings which it can process; some of these also pertain even when the target system is not an ERP adapter:

    CommunicationMode = INTERNAL or MQ
                        - Use this when TC and adapter machines are not the same machine.  Use INTERNAL when TCPIP Manager
                          is used to communicate between TC and the adapter.  Use MQ when Websphere MQ is used to
                          communicate between TC and the adapter.
  
    AdapterMachine    = Computer_address 
                        - Use this when CommunicationMode is INTERNAL to specify the IP address or hostname of
                          server machine on which the adapter is running.
  
    QueueManager      = Websphere MQ Queue manager name    // Use this when CommunicationMode = MQ
                        - Use this when CommunicationMode is MQ to specify the name of the MQ queue manager.
  
    MessageQueue      = Queue_name
                        - Regardless of the CommunicationMode, this is the name (up to 10 characters) of the primary 
                          message queue from which the adapter will read request BODs to be processed.  Therefore it 
                          is the queue to which TC will send outgoing request BODs.
  
    ConfirmQueue      = Queue_name
                        - Regardless of the CommunicationMode, this is a secondary line of communication between 
                          TC and the adapter which TC uses to confirm to the adapter that it has received the
                          response to a previous request sent on the MessageQueue.  When the adapter receives a
                          confirm message (uniquely identified by the noun-verb-referenceID combination) it frees 
                          up the buffered response that it was maintaining for that request.
  
    ResponseQueue     = Queue_name
                        - Use this when the CommunicationMode is MQ to notify the MQ transport layer the name of the
                          queue on to which responses to messages should be placed.   This parameter is ignored when
                          the CommunicationMode is INTERNAL; in this case TC generates a unique response queue name
                          using the format OWRnnnnnnn where 'nnnnnnn' is the Windows process ID of the TC session.
  
    DLLName           = The name of the Websphere MQ .DLL to use
                        - If not specified, the default name is MQM.DLL.  This parameter is ignored when the 
                          CommunicationMode is INTERNAL.
  

  The following additional options are actually only applicable on the adapter machine (set via an .INI file or the SYNC_LOGON or SYNC_ADAPTER BODs) but they are included here for completeness:

    DBG_ALL_JDE_XML   = TRUE or YES or FALSE or NO
                        - Use this option to tell the adapter to log to the debug log file all of the XML messages 
                          and responses that are exchanged with JDE for every business function call that the 
                          adapter makes.   This XML is written to the debug log regardless of the setting of the 
                          DEBUG option.
  
                          If neither DBG_ALL_JDE_XML or DBG_WARN_JDE_XML are active, then the only XML
                          that is written to the Debug log is for business functions that return an error.
  
    DBG_WARN_JDE_XML  = TRUE or YES or FALSE or NO
                        - Use this option to tell the adapter to log to the debug log file the XML messages 
                          and responses that are exchanged with JDE for every business function call that
                          returns a warning code.  The XML for business functions that return an error are
                          always written to the debug log.
  
  

  The following additional options are available when TC is communicating to other applications using MQ or the TCPIP Manager:

    OneWayMessages    = TRUE or YES or FALSE or NO
                        - If TRUE or YES, this indicates a response is not expected nor will it be looked for by TC.
                          If not specified, the default for this option is FALSE/NO.                        
  
    AtomicSends       = TRUE or YES or FALSE or NO
                        - Use this when Websphere MQ is the communication mechanism to specify that each attempt
                          to send a message is done using the sequence open-write-close rather than opening the
                          queue once to establish a "session" that all message sends are done in before the queue
                          is closed - when the application is stopped.  If not specified, the default for this
                          option is FALSE/NO.
    IncludeFinalNull  = TRUE or YES or FALSE or NO
                        - When TC communicates with the adapter, it terminates each message with a null character.
                          However, when the adapter is not the target, the target application may not require
                          the final null or may in fact consider it invalid.    If this option is not specified
                          the default value is TRUE/YES.
  
    UseCorrelationID  = TRUE or YES or FALSE or NO
                        - Use this when the CommunicationMode is MQ to notify the MQ transport layer that it 
                          should use a correlation ID to pair up outgoing messages with their incoming responses.
                          Use of the correlation ID allows the internal message processing code for XML_Send /
                          XML_SendBOD to ignore stale responses and know which response is the corresponding response 
                          for the message that it last sent.  If not specified, this option defaults to FALSE / NO.
                          If MQ is not putting a correlation ID in the outgoing message the internal message 
                          processing code blanks out this field in the outgoing message and expects it to be blank
                          in the response message.
  
    DontCheckCorrelationID = TRUE or YES or FALSE or NO
                        - Use this when the CommunicationMode is MQ to notify the internal message processing code
                          for XML_Send / XML_SendBOD not to check for a matching correlation ID - even if they
                          are being put into the outgoing and incoming messages (even if UseCorrelationID is 
                          true).   This can be useful in testing when test response messages are being added to 
                          the queue and therefore the correlation ID in these test messages will likely not
                          match.   If not specified, this option defaults to FALSE / NO.
  
  

  The following options controlling the logging that is done within TCXML.DLL, CXML.DLL and ADPTUTIL.DLL on the TC machine; they do not affect the adapter. But they do affect TCPIP Manager on the TC machine, it it is being use:

    LogLevel          = A number from 0-150
                        - This controls how much trace and debug information is written to the trace and debug
                          logs.  If not specified, the default value is 0.   The higher the number, the more
                          information is logged.   Be careful not to set this value too high, especially in a
                          production environment, because the more data that is logged, the greater the chance
                          that performance will be negatively impacted.
  
                          The LogLevel affects the amount of data that is written to the Trace log files 
                          (specified by the LogFile/TraceFile parameter) whereas the Debug Y/N flag affects
                          what data is written to the Debug log files.
  
    LogFile           = [path\]filename.ext
                        - This is the name of the file to which trace data should be written; if not specified, 
                          the default file name is TRACE.LOG.  The path is optional.  If not specified, the
                          file will be generated in the current directory - relative to where TC was started.
                          If the LogCount is something other than 0, the [path\]filename.ext specified will have 
                          a dot and 4-digit number added to it so that multiple logfiles can exist at the same 
                          time.  See the LogSize/TraceSize and LogCount/TraceCount below for more information.
                          Trace data includes high level information about what steps are being performed.  It
                          also includes error messages.
  
    LogCount          = Maximum number of tracelogs to keep at one time
                        - The LogCount defaults to 0, if not specified.   If the LogCount is set to something 
                          other than 0 then as logfiles fill up, new ones are created with an ever-incrementing 
                          numeric extension (wrapping back to 0000 after reaching 9999).  The LogCount specifies 
                          how many LogFiles should be kept at one time.  If the maximum number of logfiles 
                          already exist and a new one must be created, the oldest one is deleted.  If LogCount 
                          is 0, then a single file is used and its size is not limited (LogSize parameter is
                          ignored).   In this case, procedures should be in place to periodically archive and
                          delete this file so that it does not become excessively large.
  
    LogSize           = Maximum size, in bytes, that each trace logfile can grow to
                        - When multiple logfiles are being used, the LogSize controls how big each file will
                          grow to before the next logfile is used.  If not specified, the default size is 
                          set to 10,000,000 bytes.
  
    TraceFile         = This is a synonym for LogFile
    TraceSize         = This is a synonym for LogSize
    TraceCount        = This is a synonym for LogCount
  
    Debug             = TRUE or YES or FALSE or NO
                        - When this option is TRUE / YES then more detailed information is written to the debug
                          logs about the steps that are being performed.
  
    DebugFile         = [path\]filename.ext
                        - This is the name of the file to which debug data should be written; if not specified, 
                          the default file name is DEBUG.LOG.  The path is optional.  If not specified, the
                          file will be generated in the current directory - relative to where TC was started.
                          If the DebugCount is something other than 0, the [path\]filename.ext specified will have 
                          a dot and 4-digit number added to it so that multiple debug files can exist at the same 
                          time.  See the DebugSize and DebugCount below for more information.  Debug data 
                          includes more detailed information about what steps are being performed. While not 
                          relevant for the TC machine, the debug log also includes any XML messages for JDE
                          errors as well as XML generated from turning on the options DBG_WARN_JDE_XML or
                          DBG_ALL_JDE_XML.
  
    DebugCount        = Maximum number of debug logs to keep at one time
   
                        - This parameter is similar to LogCount/TraceCount except that it applies to the 
                          debug logfiles.
  
    DebugSize         = Maximum size, in bytes, that each debug logfile can grow to
   
                        - This parameter is similar to LogSize/TraceSize except that it applies to the 
                          debug logfiles.
  
    DONT_PRINT_POINTERS = TRUE or YES or FALSE or NO
                        - When this option is TRUE / YES, then any message that might include a pointer value
                          (an 8 digit hex number) will instead put the text "HidePointer" in the message instead
                          of the hex value.  This make it easier to do text comparisons between messages from
                          failing and working scenarios.   If not specified, the default is FALSE / NO.
  
  

  Example:
   
    // Use the function XMLSendMessage in AdptUtil.Dll to send XML messages
    XML_Sender ( AdptUtil.Dll:XMLSendMessage )
   
    // Configure the send function to use the message queue named 'ERP01'
    XML_Configure ( "MessageQueue = ERP01" )
   
    // Configure the send function to use the confirm queue named 'ERP02'
    Set_UV_Kbd_Data (UV1, "ConfirmQueue = ERP02")
    XML_Configure (UV1)
  

  XML_CopyElement

    XML_CopyElement( Target_Handle_UV, Source_Handle_UV, Element_name* [ [, Attribute_name*], Attribute_value*]
                         [, Occurrence*], Error_label )
  

  XML_CopyElement copies the specified element and any children from the current position in the source XML message to the current position in the target XML message. If no element matches the specified parameters, the script will branch to the provided error label.

  All parameters, except the first two user variables and error label, can be specified as a quoted string, a user variable, or a data part.

  Target_Handle_UV	A user variable which contains the handle for the XML message into which the source element will be copied. Before performing the copy, use XML_EnterElement to navigate to the correct position in the target XML message.
  Source_Handle_UV	A user variable which contains the handle for the source XML message from which the specified element will be copied. Before performing the copy, use XML_EnterElement to navigate to the correct position in the source XML message.
  Element_name*	The name of the element which should be copied. Element names are case sensitive.
  Attribute_name*	The case sensitive name of the attribute which should be matched in the element. This is an optional field. If Attribute_value is set and Attribute_name is not set, it will default to 'qualifier'.
  Attribute_value*	The value of the attribute which should be matched in the element. This is an optional field.
  Occurrence*	The occurrence of the element which should be copied. This is used if there are several elements with the same name which need to be iterated through. In that case, the script should specify the occurrence in a user variable which is incremented as the data in the child nodes is used. This field is optional; however, it must be specified if the Attribute_value is set. The default is '1' if it is not provided.
  Error_label	Script label to go to if the element cannot be found.

  Example:
   
      // Copy all of the LISTDETAIL elements at the current position
      // in the source XML message to the target XML message
      Set_UV_Kbd_Data (UV2, "1")
  
      // Move to the LISTHEADER in the target XML message under which the
      // the LISTDETAIL elements from the source XML message will be copied.
      XML_EnterElement (targetXMLUV, "LISTHEADER", Label2)
  
    LoopTop:
      XML_CopyElement (targetXMLUV, sourceXMLUV, "LISTDETAIL", UV2, Label2)
    
      // Increment the loop conter
      UV_Math (UV2, +, 1)
      Goto (LoopTop)
   
    Label2:
  

  XML_Create

    XML_Create( UV [, File_name* ] )
  

  XML_Create creates an empty XML message containing only the following prolog information:

    <?xml version="1.0" standalone="yes"?>
    <!DOCTYPE first_node SYSTEM "File_name">
  

  where 'File_name' is the value obtained from the second parameter of this command and 'first_node' is taken from the first element that is added to the XML message. However, if the File_name parameter is omitted, then the entire DOCTYPE/SYSTEM element is not included in the prolog.

  The second parameter can be specified as a quoted string, a user variable, or a data part.

  UV	A user variable which will hold the handle for the XML message when the command completes. The handle is used in all other XML commands to access data in the XML message. If the returned handle is 0, an error occurred while creating the XML message.
  File_name*	The optional name of the file which contains the DTD for this XML message. The file is intended to be used for validation of the XML data which is placed in the message. Note: However no validation is currently done on XML data; this will be a future enhancement.

  Examples:
   
    // 1. Create an empty XML message that will eventually confrom to the document type
    // sync_logon_001.dtd when we are done building it.  The handle is returned in UV1.
    XML_Create( UV1, "sync_logon_001.dtd")
  

  Generates an empty XML message with the following prolog:

    <?xml version="1.0" standalone="yes" ?>
    <!DOCTYPE first_node SYSTEM "sync_logon_001.dtd" >
  

    // 2. Create an empty XML message that is not tied to any specific document type.  The
    // handle is returned in UV1.
    XML_Create( UV1)
  

  Generates an empty XML message with the following prolog:

    <?xml version="1.0" standalone="yes" ?>
  

  XML_CreateBOD

    XML_CreateBOD( UV, File_name* )
  

  XML_CreateBOD creates an XML message and inserts the BOD (Business Object Document) specific header information into the message. The BOD header information is defined by OAG and is initially set as follows (with the VERB, NOUN, and REVISION filled in appropriately):

    <CNTROLAREA>
       <BSR>
          <VERB>
             VERB
          </VERB>
          <NOUN>
             NOUN
          </NOUN>
          <REVISION>
             REVISION
          </REVISION>
       </BSR>
       <SENDER>
          <LOGICALID></LOGICALID>
          <COMPONENT></COMPONENT>
          <TASK></TASK>
          <REFERENCEID></REFERENCEID>
          <CONFIRMATION></CONFIRMATION>
          <LANGUAGE></LANGUAGE>
          <CODEPAGE></CODEPAGE>
          <AUTHID></AUTHID>
       </SENDER>
       <DATETIME qualifier="CREATION">
          <YEAR>
             Current year
          </YEAR>
          <MONTH>
             Current month
          </MONTH>
          <DAY>
             Current day
          </DAY>
          <HOUR>
             Current hour
          </HOUR>
          <MINUTE>
             Current minute
          </MINUTE>
          <SECOND>
             Current second
          </SECOND>
          <SUBSECOND>
             Current milliseconds
          </SUBSECOND>
          <TIMEZONE>
             Current timezone
          </TIMEZONE>
       </DATETIME>
    </CNTROLAREA>
  

  The second parameter can be specified as a quoted string, a user variable, or a data part.

  UV

  A user variable which will hold the handle for the XML message when the command completes. The handle is used in all other XML commands to access data in the XML message. If the returned handle is 0, an error occurred while creating the XML message.

  File_name*

  The name of the file which contains the DTD for this XML message. The file is used for validation of the XML data which is placed in the message. Note: No validation is currently done on XML data. This will be a future enhancement. Currently, the file name is used to determine the NOUN, VERB, and REVISION information for the BOD. The file name is assumed to be of the form VERB_NOUN_REVISION.dtd or nnn_VERB_NOUN_REVISION.dtd where nnn is a numeric value.

  Example:
   
    // Create a SYNC_LOGON BOD with the format described in
    // the sync_logon_001.dtd file
    XML_CreateBOD( UV1, "sync_logon_001.dtd")
  

  Generates the following structure (with the apropriate time):

    <?xml version="1.0" standalone="yes" ?>
    <!DOCTYPE SYNC_LOGON_001 SYSTEM "sync_logon_001.dtd" >
       <SYNC_LOGON_001>
          <CNTROLAREA>
             <BSR>
                <VERB>
                   SYNC
                </VERB>
                <NOUN>
                   LOGON
                </NOUN>
                <REVISION>
                   001
                </REVISION>
             </BSR>
             <SENDER>
                <LOGICALID></LOGICALID>
                <COMPONENT></COMPONENT>
                <TASK></TASK>
                <REFERENCEID></REFERENCEID>
                <CONFIRMATION></CONFIRMATION>
                <LANGUAGE></LANGUAGE>
                <CODEPAGE></CODEPAGE>
                <AUTHID></AUTHID>
             </SENDER>
             <DATETIME qualifier="CREATION">
                <YEAR>
                   1999
                </YEAR>
                <MONTH>
                   7
                </MONTH>
                <DAY>
                   19
                </DAY>
                <HOUR>
                   10
                </HOUR>
                <MINUTE>
                   39
                </MINUTE>
                <SECOND>
                   1
                </SECOND>
                <SUBSECOND>
                   792
                </SUBSECOND>
                <TIMEZONE>
                   -0500
                </TIMEZONE>
             </DATETIME>
          </CNTROLAREA>
       </SYNC_LOGON_001>
  

  XML_CreateElement

    XML_CreateElement( UV, Element_name* [ [, Attribute_name*], Attribute_value*]  )
  

  XML_CreateElement creates an element and makes that element the current one. Commands such as XML_AddField or XML_CreateElement will be relative to the newly created element until a XML_LeaveElement is executed to move out of that element.

  All parameters, except the first user variable, can be specified as a quoted string, a user variable, or a data part.

  UV	A user variable which contains the handle for the XML message. It was returned by a previous call to XML_Create, XML_CreateBOD, XML_Send, XML_SendBOD, or XML_Parse
  Element_name*	The name of the element which should be created and made current. The name is case sensitive.
  Attribute_name*	The case sensitive name of the attribute which should be set in the element. This is an optional field. If Attribute_value is set and Attribute_name is not set, it will default to 'qualifier'.
  Attribute_value*	The value of the attribute which should be set in the element. This is an optional field.

  Examples:
   
    // Create a DATAAREA element under the current position and
    // move the current position into that node
    XML_CreateElement (UV1, "DATAAREA")
   
    // Create a DATETIME element with attribute 'qualifier' with value 'CREATION'
    XML_CreateElement (UV1, "DATETIME", "CREATION")
   
    // or
    XML_CreateElement (UV1, "DATETIME", "qualifier", "CREATION")
  

  XML_DefineNamespace

    XML_DefineNamespace( uvXMLDocument, URI*, Namespace_Abbreviation*)
  

  A series of one or more XML_DefineNamespace commands is used in conjunction with the XML_RedefineNamespaces command in order to remap the URI-to-namespace mappings (URI = Uniform Resource Identifier) in an XML document that is already being referenced by a user variable. The main intent is to normalize the handling of an XML response returned by the XML_Send / XML_SendBOD commands. However it could also be used on an XML document that a UV references from an XML_Parse or XML_Create / XML_CreateBOD command.

  The two namespace commands allow a TC script to consistently navigate an XML document even if the originator of the message might change the namespace abbreviations that are associated with each URI (e.g. because the namespaces are auto-generated during a compile / configure / build operation). These commands rely on the fact that although the abbreviations might change, the URIs to which they are mapped should remain the same for a given XML document.

  For a given XML document, the XML_DefineNamespace command should be repeated for each unique URI in the document that might change. TC accumulates the set of alternate abbreviation-to-URI mappings, storing them with the document. Then when XML_RedefineNamespaces is called for the document, TC will regenerate the document using the alternate abbreviations.

  After that point all of the XML_EnterElement, XML_GetField / XML_GetField2, XML_CopyElement, ... commands for that document can use the set of abbreviations that were used in the XML_DefineNamespace commands for the document.

  In the following example raw XML message:

  	<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
          	<soapenv:Body>
                  	<p:getSUInformationResponse xmlns:p="http://CommonObjects/PTS">
                          	<shippingUnit xmlns:tnt="http://com/ibm/swg/iss/tnt/" />
  	                        <result xmlns:tnt="http://com/ibm/swg/iss/tnt/">
          	                        <tnt:resultCode>0</tnt:resultCode>
                  	        </result>
  	                </p:getSUInformationResponse>
          	</soapenv:Body>
  	</soapenv:Envelope>
  

  there are 3 unique abbreviation-to-namespace mappings:
  • soapenv = "http://schemas.xmlsoap.org/soap/envelope/"
  • p = "http://CommonObjects/PTS"
  • tnt = "http://com/ibm/swg/iss/tnt/"

  A TC script might perform the following commands to navigate this document:

  	XML_EnterElement(UV1, "soapenv:Body", EnterElementFailed)
  		XML_EnterElement(UV1, "p:getSUInformationResponse", EnterElementFailed)
  			XML_EnterElement(UV1, "result", EnterElementFailed)
  				XML_GetField2 (UV1, "tnt:resultCode", uvResult, GetFieldFailed)
  			XML_LeaveElement(UV1)
  		XML_LeaveElement(UV1)
  	XML_LeaveElement(UV1)
  

  But if the sender of this document changes the namespace abbreviations then the commands above would not be able to navigate the document any more. But with the use of the namespace commands as shown below, prior to the navigation commands above, the navigation commands will continue to work even when the sender changes the namespace abbreviations:

  	XML_DefineNamespace ( UV1, "http://CommonObjects/PTS",    "p" )
  	XML_DefineNamespace ( UV1, "http://com/ibm/swg/iss/tnt/", "tnt" )
  
  	XML_RedefineNamespaces ( UV1 )
  

  All parameters, except the first user variable, can be specified as a quoted string, a user variable, or a data part.

  uvXMLDocument	A user variable which contains the handle for the XML document. It was returned by a previous call to XML_Create, XML_CreateBOD, XML_Send, XML_SendBOD, or XML_Parse
  URI*	A Uniform Resource Identifier that is used in the XML document. It will be associated with the the abbreviation specified in as the third parameter. URI's are case insensitve.
  Namespace_Abbreviation*	The namespace abbreviation that is to be associated with the URI specified as the second parameter. Namespace abbreviations are case sensitive

  Example:
  
    // See the discussion above for an example 
  
  

  XML_EnterElement

    XML_EnterElement( UV, Element_name* [ [, Attribute_name*], Attribute_value*]
                         [, Occurrence*], Error_label )
  

  XML_EnterElement makes the current element the one named in the call. If an Attribute_value is provided, the element moved to will have the attribute name and value specified. If no element matches the specified parameters, the script will branch to the provided error label. This call is the primary method of moving through a return message although it can also be used to move through a message that is being built. It is generally used in conjunction with XML_GetField to read information from a message.

  All parameters, except the first user variable and error label, can be specified as a quoted string, a user variable, or a data part.

  UV	A user variable which contains the handle for the XML message. It was returned by a previous call to XML_Create, XML_CreateBOD, XML_Send, XML_SendBOD, or XML_Parse
  Element_name*	The name of the element which should be made current. Element names are case sensitive.
  Attribute_name*	The case sensitive name of the attribute which should be matched in the element. This is an optional field. If Attribute_value is set and Attribute_name is not set, it will default to 'qualifier'.
  Attribute_value*	The value of the attribute which should be matched in the element. This is an optional field.
  Occurrence*	The occurrence of the element which should be entered. This is used if there are several elements with the same name which need to be iterated through. In that case, the script should specify the occurrence in a user variable which is incremented as the data in the child nodes is used. This field is optional; however, it must be specified if the Attribute_value is set. The default is '1' if it is not provided.
  Error_label	Script label to go to if the element cannot be found.

  Example:
   
      // Look at all of the LISTDETAIL elements at the current position
      // and do something with their data.
      Set_UV_Kbd_Data (UV2, "1")
   
    LoopTop:
      XML_EnterElement (UV1, "LISTDETAIL", UV2, Label2)
   
      //
      // Use the data in the element
      //
   
      // Move back to the original position in preparation for
      // continuing the loop
      XML_LeaveElement (UV1)
   
      // Increment the loop conter
      UV_Math (UV2, +, 1)
      Goto (LoopTop)
   
    Label2:
  

  XML_GetField / XML_GetField2

    XML_GetField(  UVa, Field_name* [ [, Attribute_name*], Attribute_value*], UVb )
  
    XML_GetField2( UVa, Field_name* [ [, Attribute_name*], Attribute_value*] [, Occurrence*], UVb, Error_label )
  

  XML_GetField retrieves the value in an element under the current element and stores the value in UVb. If an Attribute_value is provided, data will be retrieved from an element with the specified attribute name and value. If no matching element can be found, the return user variable (UVb) will be empty. This function is crucial for retrieving information from a message and is primarily used when reading a response message.

  XML_GetField2 adds the ability to specify an Occurrence number - which can be used with or without attributes. And it adds the ability to specify an error lable; in fact the error label is required for XML_GetField2.

  All fields, except the first and last user variable, can be specified as a quoted string, a user variable, or a data part.

  UVa	A user variable which contains the handle for the XML message. It was returned by a previous call to XML_Create, XML_CreateBOD, XML_Send, XML_SendBOD, or XML_Parse
  Field_name*	The name of the element from which data should be retrieved. Field names are case sensitive.
  Attribute_name*	The case sensitive name of the attribute which should be matched in the element. This is an optional field. If Attribute_value is set and Attribute_name is not set, it will default to 'index'.
  Attribute_value*	The value of the attribute which should be matched in the element. This parameter is used to distinguish between several elements with the same name, but different attributes. If no element with the specified attribute exists, no value will be retrieved. This is an optional field.
  Occurrence*	(XML_GetField2 only) The occurrence of the element which should be entered. This is used if there are several elements with the same name which need to be iterated through. In that case, the script should specify the occurrence in a user variable which is incremented as the data in the child nodes is used. This field is optional; however, it must be specified if the Attribute_value is set. The default is '1' if it is not provided.
  UVb	The target user variable for the retrieved data.
  Error_label	(XML_GetField2 only) Script label to go to if the specified field cannot be found - or if an occurrence number is specified that is after that last available occurrence. The error label is not valid for XML_GetField but it is required for XML_GetField2.

  Examples:
   
    // Get the data in the CONFIRMATION child node
    XML_GetField (UV1, "CONFIRMATION", UV2)
   
    // Get the SITELEVEL field with attribute 'index' and attribute value '1'
    XML_GetField (UV1, "SITELEVEL",          "1", UV2)
   
    // or
    XML_GetField (UV1, "SITELEVEL", "index", "1", UV2)
  
    // Retrieve the 3rd occurrence of the field BATCH - which has no attribute - and stores the 
    // value in UV2.  If the field does not exist, branch to the label or subroutine FieldNotFound.
    XML_GetField2 (UV1, "BATCH", "3", UV2, FieldNotFound)
  
    // Retrieve the 5th occurrence of the field LOAD with attribute 'index' and attribute value '1' and stores 
    // the value in UV2.  If the field does not exist, branch to the label or subroutine FieldNotFound.
    XML_GetField2 (UV1, "LOAD", "5",          "1", UV2, FieldNotFound)
  
    // or
    XML_GetField2 (UV1, "LOAD", "5", "index", "1", UV2, FieldNotFound)
  
  

  XML_LeaveElement

    XML_LeaveElement( UV )
  

  XML_LeaveElement makes the current element the parent of the current element. This function is useful when you have previously performed an XML_EnterElement or XML_CreateElement and need to return to the previous level.

  UV	A user variable which contains the handle for the XML message. It was returned by a previous call to XML_Create, XML_CreateBOD, XML_Send, XML_SendBOD, or XML_Parse

  Example:
   
    // Enter the CNTROLAREA element
    XML_EnterElement (UV1, "CNTROLAREA", Label1)
   
      // Then enter the SENDER element beneath the CNTROLAREA element
      XML_EnterElement (UV1, "SENDER", Label1)
   
        // Set the CONFIRMATION to "2"
        XML_SetField (UV1, "CONFIRMATION", "2")
   
      // Move out of the SENDER element back to the CNTROLAREA section
      XML_LeaveElement (UV1)
   
    // Move out of the CNTROLAREA element back to the original level
    XML_LeaveElement (UV1)
  

  XML_LoadLoggingParameters

    XML_LoadLoggingParameters( Parameter_File* )
  

  XML_LoadLoggingParameters gives TC sessions the same capability to specify unique logging parameters for XML message processing - that the .INI file capability does for the adapter and TCP/IP Manager:

  The logging parameters that are supported in the specified file are the same ones that are supported in the adapter / TCPIP Manager .INI file or an XML_Configure command, including:

    LogLevel, LogFile, DebugFile, LogCount, DebugCount, LogSize, DebugSize, Debug and Dont_Print_Pointers
  

  Note that DBG_ALL_JDE_XML and DBG_WARN_JDE_XML are adapter specific logging parameters and do not apply to TC sessions.

  Also supported in the file is an IMBED= or INCLUDE= statement, used to get logging parameters from another file. You could put a majority of the parameters that will be the same into a single file and then INCLUDE that file into the unique logging parameters for each TC session.

  For example, c:\dcconn\tc\XMLLogging_Common.INI could include the following statements:

    LOGLEVEL = 0
    LOGCOUNT = 50
    DEBUGCOUNT = 50
    LOGSIZE = 2000000
    DEBUGSIZE = 2000000
    DEBUG = N
  

  and then C:\dcconn\tc\XMLLogging_A.INI could be set up for TC session A, containing the following:

    IMBED     = %tc2%\XMLLogging_Common.ini
    LOGFILE   = c:\dcconn\tc\XML_Log_Trc_A.log
    DEBUGFILE = c:\dcconn\tc\XML_Log_Dbg_A.log
  

  while C:\dcconn\tc\XMLLogging_B.INI could be set up for TC session B, containing the following:

    IMBED     = %tc2%\XMLLogging_Common.ini
    LOGFILE   = c:\dcconn\tc\XML_Log_Trc_B.log
    DEBUGFILE = c:\dcconn\tc\XML_Log_Dbg_B.log
  

  As is shown above, environment variables can be used in the IMBED / INCLUDE statement but they cannot be used in the LOGFILE / DEBUGFILE statements. Environment variables can also be used in the new TC command XML_LoadLoggingParameters.

  If the same parameter is encountered more than once when processing the file or any imbedded file, the last occurrence of that parameter is the one that will take effect.

  The XML_LoadLoggingParameters command should be part of the StartLogon script to ensure the logging parameters are set up before the TC script attempts to do any XML operations that might cause logging to be done. But it should be after the XML_Sender command that is typically used to specify that ADPTUTIL.DLL is the .DLL that should be used for the XML_Send / XML_SendBOD functions and other XML functions. For example:

    XML_Sender (AdptUtil.Dll:SendXMLMessage)
  

  When the XML_LoadLoggingParameters command is performed, TC remembers the file name that is specified, after resolving any imbedded environment variables, so that the logging parameters can be reloaded when the user selects the menu option Trace -> Reload XML Logging Parameters. If you want to temporarily change a logging parameter, such as the loglevel, you could add it to the parameter file for a specific session, such as the example XMLLogging_A.ini above, and then use the new menu option to reload the parameters. When you want the logging level set back to the value in XMLLogging_Common.INI shown above, remove it from XMLLogging_A.ini and use the menu option to reload.

  Using this menu option is similar to pressing the R key to reload the parameter file for an adapter or TCPIP Manager session.

  Whenever the XML logging parameters are loaded for a particular TC session, a message is logged to the bottom window of the TC session and to the TC error log for that session.

  Parameter_File*

  A user variable, quoted string, or data part indicating the file that contains the logging parameters. If a quoted string, it can include environment variables which will be resolved when the script is compiled.

  Example:
   
    StartLogon() 
  
      // Use the function XMLSendMessage in AdptUtil.Dll to send XML messages
      XML_Sender ( AdptUtil.Dll:XMLSendMessage )
   
      // Configure the send function to use the message queue named 'ERP01'
      XML_LoadLoggingParameters ( "C:\XML_LOG_PARMS_A.INI" )
  
      ...
   
  

  XML_Parse

    XML_Parse ( UV, XML_String*, Error_label )
  

  XML_Parse parses an XML message / string, and returns a new XML handle which can be used to explore and modify the XML message.

  UV	A user variable which will contain the handle for the returned XML message.
  XML_String*	A user variable, data part, or literal string which containts the XML message to be parsed.
  Error_label	Label to goto if unable to parse the message (ie. the string is not a valid XML message).

  Example:
   
      // Open a data file to retrieve the XML message from
      Open_File_Data (UV1, "XML_Data_File.xml")
   
      // Read the message into a user variable
      Set_UV_File_Data (UV2, UV241, 0)
   
      // Close the data file
      Close_File_Data ()
   
      // Parse the message to create a handle
      XML_Parse (UV1, UV241, Label4)
   
      // Send the BOD
      XML_SendBOD (UV1, UV2, 60, Label1)
   
      // Cleanup the XML message
      XML_Cleanup (UV1)
   
      // Do something with the return message
   
      // Cleanup the returned message
      XML_Cleanup (UV2)
   
      // Skip the error label part
      Goto Label2
   
    Label1:
   
      // Cleanup the XML message
      XML_Cleanup (UV1)
   
    Label2:
  

  XML_RedefineNamespaces

    XML_RedefineNamespaces( uvXMLDocument )
  

  This command is used after a series of one or more XML_DefineNamespace commands in order to remap the URI-to-namespace mappings (URI = Uniform Resource Identifier) in an XML document that is already being referenced by a user variable.

  Please see XML_DefineNamespace for a complete explanation of these two commands.

  uvXMLDocument

  A user variable which contains the handle for the XML document. It was returned by a previous call to XML_Create, XML_CreateBOD, XML_Send, XML_SendBOD, or XML_Parse

  Example:
  
    // see XML_DefineNamespace
  
  

  XML_Send

    XML_Send ( UVa, UVb, Timeout, Error_label )
    XML_Send ( RAW, UVa, UVb, Timeout, Error_label )
   
  

  XML_Send sends an XML message, and returns a new XML message to Transaction Connection. If the return message does not come in the timeout specified, control is passed to the label specified.

  This command calls the function specified in XML_Sender to actually transmit the message.

  As of April 2006, TC supports the use of the keyword RAW as the first parameter to indicate that instead of sending an XML formatted message, TC should instead the contents of the user variable in its raw format, i.e. as it is in the user variable. In this case the response that is received for the message is also assumed to be raw and will therefore be stored as is.

  Use of the RAW parameter requires a version of ADPTUTIL.DLL from April 2006 or later.

  UVa	If the keyword RAW is at the beginning of the command, UVa must contain the raw message that is to be sent. Otherwise, this is the user variable which contains the handle for the XML message. It was returned by a previous call to XML_Create, XML_CreateBOD, XML_Send, XML_SendBOD, or XML_Parse
  UVb	If the keyword RAW is at the beginning of the command, uvB will be the UV where the response to the message will be stored. It will be restored in its raw format. Otherwise, this is the user variable which will contain the handle for the returned XML message.
  Timeout	The communication timeout in seconds
  Error_label	Label to goto if the communications timeout expires before a return message is received.

  Example:
   
      // Create a SYNC LOGON
      XML_Create (UV1, "sync_logon_001.dtd")
   
      // Add data to the message
   
      // Send the message
      XML_Send (UV1, UV2, 60, Label1)
   
      // Cleanup the XML message
      XML_Cleanup (UV1)
   
      // Do something with the return message
   
      // Cleanup the returned message
      XML_Cleanup (UV2)
   
      // Skip the error label part
      Goto Label2
   
    Label1:
   
      // Cleanup the XML message
      XML_Cleanup (UV1)
   
    Label2:
  

  XML_SendBOD

    XML_SendBOD ( UVa, UVb, Timeout, Error_label )
  

  XML_SendBOD sends an XML message containing a BOD, and returns a new XML message, containing a BOD, to Transaction Connection. If the return message does not come in the timeout specified, control is passed to the label specified.

  This command calls the function specified in XML_Sender to actually transmit the message.

  UVa	A user variable which contains the handle for the XML message in the BOD format. It was returned by a previous call to XML_CreateBOD, XML_SendBOD, or XML_Parse.
  UVb	A user variable which will contain the handle for the returned XML message.
  Timeout	The communication timeout in seconds
  Error_label	Label to goto if the communications timeout expires before a return message is received.

  Example:
   
      // Create a SYNC LOGON BOD
      XML_CreateBOD (UV1, "sync_logon_001.dtd")
   
      // Add data to the message
   
      // Send the BOD
      XML_SendBOD (UV1, UV2, 60, Label1)
   
      // Cleanup the XML message
      XML_Cleanup (UV1)
   
      // Do something with the return message
   
      // Cleanup the returned message
      XML_Cleanup (UV2)
   
      // Skip the error label part
      Goto Label2
   
    Label1:
   
      // Cleanup the XML message
      XML_Cleanup (UV1)
   
    Label2:
  

  XML_Sender

    XML_Sender ( DLL_name )
    XML_Sender ( DLL_name:Function_name )
  

  This function is used to specify a custom function to use when sending an XML message to another application. The system will dynamically load the given function from the specified dynamic link library. If no function name is provided, a default of SendXMLMessage will be used. If the function cannot be found, TC will generate an error when starting indicating that the function could not be loaded from the library specified.

  The default behavior of the system (which uses TCXML.DLL) is to write XML messages to a disk file whenever XML_Send or XML_SendBOD is called. If that behavior needs to be changed, it is necessary to call XML_Sender to set up a different method of transmitting XML messages.

  One example of this need to modify the default behavior can exist when using an ERP adapter. The user can choose to send XML messages directly to the ERP adapter by using this command:

    XML_Sender ( ERPAdptr.Dll )
   
      or
   
    XML_Sender ( ERPAdptr.Dll:SendXMLMessage )
  

  or can send the message to a remote copy of the adapter (a typical method that is used) by specifying:

    XML_Sender ( AdptUtil.Dll )
   
      or
   
    XML_Sender ( AdptUtil.Dll:SendXMLMessage )
  

  DLL_name

  The name of the dynamic link library where the send function should be found. The 'normal' rules apply for finding the DLL (first check the directory where the application loaded, then check the current directory, then the system directory, then the windows directory, and finally the path).

  Function_name

  The name of the function to be loaded from the dynamic link library. Note: The following information is for sophisticated users who need to write their own function for sending XML messages. The functionality provided by TC and the IBM ERP products should fulfill the needs of most users. The function should have the following prototype int __cdecl SendXMLMessage (char *Output, char **Input, long Timeout); Output The message which should be transmitted. Input The location where any response message should be stored. Timeout The time in seconds that the function should wait before returning an error.

  The value returned by the function should be 0 for success, and any other value to indicate a failure (either a timeout or a general failure).

  Example:
   
    // Use SendXMLMessage2 in library AdptUtil.Dll to transmit XML messages
    XML_Sender ( AdptUtil.Dll:SendXMLMessage2 )
  

  XML_SetField

    XML_SetField( UV, Field_name* [ [, Attribute_name*], Attribute_value*], Data* )
  

  XML_SetField sets the value in an element to the value specified. It is the same as XML_AddField except the element (including the attribute name and value) MUST already exist.

  All fields, except the first user variable, can be specified as a quoted string, a user variable, or a data part.

  UV	A user variable which contains the handle for the XML message. It was returned by a previous call to XML_Create, XML_CreateBOD, XML_Send, XML_SendBOD, or XML_Parse
  Field_name*	The name of the element which should be set. Field names are case sensitive.
  Attribute_name*	The case sensitive name of the attribute which should be matched in the element. This is an optional field. If Attribute_value is set and Attribute_name is not set, it will default to 'index'.
  Attribute_value*	The value of the attribute which should be matched in the element. This parameter is used to distinguish between several elements with the same name, but different attributes. If no element with the specified attribute exists, no value will be set. This is an optional field.
  Data*	The value to be set in the element.

  Example:
   
    // Set the data in the CONFIRMATION child node to "2"
    XML_SetField (UV1, "CONFIRMATION", "2")
   
    // Set the SITELEVEL field with attribute 'index' and attribute value '1' to 'M30'
    XML_SetField (UV1, "SITELEVEL", "1", "M30")
   
    // or
    XML_SetField (UV1, "SITELEVEL", "index", "1", "M30")
  

  XML_ToFile

    XML_ToFile ( UV_Handle, FILENAME     [, RC_UV ] )
    XML_ToFile ( UV_Handle, FILENAME.EXT [, RC_UV ] )
    XML_ToFile ( UV_Handle, FILE_UV      [, RC_UV ] )
  

  The operation of this command is similar to the Log_Data command with the following differences:

  • The source is a handle to an XML message which will be 'serialized' into a string and then written to the specified file.
  • The MODE parameter is not available for XML_ToFile; all file operations are OVERWRITE.

  Please see Log_Data for more information, including more information about the second and third parameters below.

  UV_Handle	A user variable which contains the handle for the XML message.
  FILENAME, FILENAME.EXT, or FILE_UV	The file name for the data file. If a quoted string, it can include environment variables which will be resolved when the script is compiled.
  RC_UV	This is the optional return code user variable.

  Example:
  
      Name_UV(UV1,   uvRC)
  
      Name_UV(UV248, uvRequestMessage)
      Name_UV(UV249, uvResponseMessage)
      
      ...
     
      // Send outgoing message and wait for response
      XML_Send_BOD (uvRequestMessage, uvResponseMessage, 60, ErrorLabel)
   
      // Write the response to file
      XML_ToFile(uvResponseMessage, "c:\Response.XML", uvRC)
   
      // Do something with the return message
   
      // Cleanup the returned message
      XML_Cleanup (UV2)
   
      // Skip the error label part
      Goto Label2
   
    ErrorLabel:
   
      // Handle error
   
    Label2:
   
      // Cleanup the XML message
      XML_Cleanup (UV1)
  

  XML_ToString

    XML_ToString ( UV_Handle, UV_Target )
  

  This is the converse of the XML_Parse command; it takes a handle to an XML message and generates the 'serialized' string in the UV_Target from that XML message.

  UV_Handle	A user variable which contains the handle for the XML message.
  UV_Target	The target user variable in which to store the string that represents the serialized XML message.

  If the specified UV_Target is not large enough for the XML string, the string will be stored up to the length of the user variable and a message will be logged indicating that truncation occurred; in addition the LAST_ERROR data part will be set to -6.

  Example:
  
      Name_UV(UV1,   uvRC)
  
      Name_UV(UV248, uvRequestMessage)
      Name_UV(UV249, uvResponseMessage)
      Name_UV(UV250, uvSerializedMessage)
  
      ...
     
      // Send outgoing message and wait for response
      XML_Send_BOD (uvRequestMessage, uvResponseMessage, 60, ErrorLabel)
   
      // Convert the response message to a string
      XML_ToString(uvResponseMessage, uvSerializedMessage)
   
      // Write the serialized message to a file
      Log_Data("c:\Response.xml", uvSerializedMessage, OVERWRITE, uvRC)
   
      // Do something with the return message
   
      // Cleanup the returned message
      XML_Cleanup (UV2)
   
      // Skip the error label part
      Goto Label2
   
    ErrorLabel:
   
      // Handle error
   
    Label2:
   
      // Cleanup the XML message
      XML_Cleanup (UV1)
  

  ---

  Compile/Run Error Messages

  Transaction Connection (TC) may return the following error messages during compiling or running of your script. Upon encountering SQL errors, additional error message information is available in the error log file.

  For information on a specific message, select the message from the following table.
  <-- We put blanks for all the BOD related messages

  XIS001	XIS002	XIS003	XIS004	XIS005	XIS006	XIS007	XIS008	XIS009	XIS010
  XIS011	XIS012	XIS013	XIS014	XIS015	None	XIS017	XIS018	XIS019	XIS020
  XIS021	XIS022	XIS023	XIS024	XIS025	XIS026	XIS027	XIS028	XIS029	XIS030
  XIS031	XIS032	XIS033	XIS034	XIS035	XIS036	XIS037	XIS038	XIS039	XIS040
  XIS041	XIS042	XIS043	XIS044	XIS045	XIS046	XIS047	XIS048	XIS049	XIS050
  XIS051	XIS052	XIS053	XIS054	XIS055	XIS056	XIS057	XIS058	XIS059	XIS060
  XIS061	XIS062	XIS063	XIS064	XIS065	XIS066	XIS067	XIS068	XIS069	XIS070
  XIS071	XIS072	XIS073	XIS074	XIS075	XIS076	XIS077	XIS078	XIS079	XIS080
  XIS081	XIS082	XIS083	XIS084	XIS085	XIS086	XIS087	XIS088	XIS089	XIS090
  XIS091	None	XIS093	XIS094	XIS095	XIS096	XIS097	XIS098	XIS099	XIS100
  XIS101	XIS102	XIS103	XIS104	XIS105	XIS106	XIS107	XIS108	XIS109	XIS110
  XIS111	XIS112	XIS113	XIS114	XIS115	XIS116	XIS117	XIS118	XIS119	XIS120
  XIS121	XIS122	XIS123	XIS124	XIS125	XIS126	XIS127	XIS128	XIS129	XIS130
  XIS131	XIS132	XIS133	XIS134	XIS135	XIS136	XIS137	XIS138	XIS139	XIS140
  XIS141	XIS142	XIS143	XIS144	XIS145	XIS146	XIS147	XIS147	XIS149	XIS150
  XIS151	XIS152	XIS153	XIS154	XIS155	XIS156	XIS157	XIS158	XIS159	XIS160
  XIS161	None	XIS163	XIS164	XIS165	XIS166	XIS167	XIS168	XIS169	XIS170
  XIS171	XIS172	XIS173	XIS174	XIS175	XIS176	XIS177	XIS178
  									XIS200
  XIS201	XIS202	XIS203	XIS204	XIS205	XIS206	XIS207	XIS208	XIS209	XIS210
  XIS211	XIS212	XIS213	None	XIS215	XIS216	XIS217	XIS218	XIS219	XIS220
  XIS221	XIS222	XIS223	XIS224	XIS225	XIS226	XIS227	XIS228	XIS229	XIS230
  XIS231	XIS232	XIS233	XIS234	XIS235	XIS236	XIS237	XIS238	XIS239	XIS240
  XIS241	XIS242	XIS243	XIS244	XIS245	XIS246	XIS247	XIS248	XIS249	XIS250
  XIS251	XIS252	XIS253	XIS254	XIS255	XIS256	XIS257	XIS258	XIS259	XIS260
  XIS261	XIS262	XIS263	XIS264	XIS265	XIS266	XIS267	XIS268	XIS269	XIS270
  XIS271	XIS272	XIS273	XIS274	XIS275	XIS276	XIS277	XIS278	XIS279	XIS280
  XIS281	XIS282	XIS283	XIS284	XIS285	XIS286	XIS287	XIS288	XIS289	XIS290
  XIS291	XIS292	None	XIS294	XIS295	XIS296	XIS297	XIS298	XIS299	XIS300
  XIS301	XIS302	XIS303	XIS304	XIS305	XIS306	XIS307	XIS308

  ---

  XIS001

  No or improper parameters on command line.

  You did not specify any command line parameters, or you specified an incorrect quantity of parameters. Enter TC2 on the command line by itself to get online help for the command line, or see Configuring an ODBC Data Source.

  ---

  XIS002

  The command file file name does not exist.

  Check the path and name of the command file specified on the command line. The file may be in exclusive use (deny all) by another process.

  ---

  XIS003

  Data Collection program is not running.

  Restart DCConnect and your TC session(s).

  ---

  XIS004

  Data Collection program is shutting down.

  Restart DCConnect and your TC session(s).

  ---

  XIS005

  Data Collection program had an operating system error.

  Correct any problem as indicated by the operating system error, then restart DCConnect and your TC session(s).

  ---

  XIS006

  Data Collection program is already using this export (mailbox) ID.

  Each application that attempts to read transactions from DCConnect must use a unique Mailbox when opening the connection to DCConnect. Check that you have not already started a TC session with this mailbox, or that there is no other application running that uses this mailbox.

  ---

  XIS007

  Data Collection program does not know this mailbox.

  Before attempting to use an mailbox with DCConnect, you must configure the mailbox name in DCConnect, including assignment of transactions from the terminals to this mailbox. The spelling and capitalization of the name must match exactly between the DCConnect configuration and your command line usage.

  ---

  XIS008

  Data collection program had error opening/reading/writing/seeking in file.

  DCConnect had a file error when trying to perform a file operation on behalf of an API request made by TC. This may be for one of the following DCConnect APIs: DcxWriteTransaction, DcxSubmitValidationFile, DcxReadTransaction, or DcxReleaseTransaction. The return code -400 was returned by the API.

  Please refer to the DCConnect message log for more information about what went wrong and refer to the DCConnect Technical Reference for more information about what the return code means for the specific API.

  ---

  XIS009

  Data Collection program transaction record is too long.

  The buffer allocated for receipt of data from a DCConnect API was not large enough to hold the data. Contact your IBM support representative.

  ---

  XIS010

  DCConnect reported error ##.

  Any API call to DCConnect reported the specified return code. Following is a table of the 32-bit DCConnect API return codes. Use the DCConnect Technical Reference to get more details about the meaning of the return code.

    32-bit DCConnect Return Codes
    -----------------------------
       6 DCX_NO_DATA
       5 DCX_NAK
       4 DCX_DC2
       3 DCX_DC1
       2 DCX_DATA
       1 DCX_ACK
   
       0 DCX_NO_ERROR
   
      -1 DCX_INTERNAL_ERROR
      -2 DCX_NOT_RUNNING
      -3 DCX_SHUTDOWN_IN_PROGRESS
      -4 DCX_STARTING_UP
   
    -100 DCX_OS_ACCESS
    -101 DCX_OS_GET_PROC
    -102 DCX_OS_MEMORY
    -103 DCX_OS_MSGPATH_CREATE
    -104 DCX_OS_MSGPATH_OPEN
    -105 DCX_OS_MSGPATH_READ
    -106 DCX_OS_MSGPATH_WRITE
    -107 DCX_OS_SEM
    -108 DCX_OS_START_TASK
    -109 DCX_CS2_NLS_ERROR
   
    -200 DCX_DELETE_FAILED
    -201 DCX_DID_NOT_REPLY
    -202 DCX_FILE_LOADING
    -203 DCX_NO_MORE_ROOM
    -204 DCX_NO_REQUEST_PENDING
    -205 DCX_PARTIAL_SUCCESS
    -206 DCX_READ_PENDING
    -207 DCX_TIMEOUT
    -208 DCX_TXTNS_TO_RELEASE
    -209 DCX_APPL_NOT_REGISTERED
    -210 DCX_READ_FAILED
    -211 DCX_READ_SUCCESS_NO_REPLY
    -212 DCX_WRITE_FAILED
   
    -300 DCX_ACQUIRED
    -301 DCX_BAD_STATUS
    -302 DCX_BAD_TERMINAL
    -303 DCX_CMD_NOT_ALLOWED
    -304 DCX_DOWNLOADING
    -305 DCX_FLUSH_FAIL
    -306 DCX_FLUSHING
    -307 DCX_INVALID_TERMINAL_TYPE
    -308 DCX_NOT_RESPONDING
    -309 DCX_REJECTED_DATA
    -310 DCX_TERM_IN_WRONG_STATE
   
    -400 DCX_FILE_ERROR
    -401 DCX_INVALID_FILE_FORMAT
   
    -500 DCX_DATA_TRUNCATED
    -501 DCX_DOES_NOT_EXIST
    -502 DCX_INVALID_ATTRIBUTE
    -503 DCX_INVALID_COMM_LINE
    -504 DCX_INVALID_COMM_LOC
    -505 DCX_INVALID_DATALEN
    -506 DCX_INVALID_DATETIME
    -507 DCX_INVALID_DURATION
    -508 DCX_INVALID_DWNLD_FILES
    -509 DCX_INVALID_DWNLD_WAIT
    -510 DCX_INVALID_ERASE
    -511 DCX_INVALID_FILE
    -512 DCX_INVALID_GLOBAL_VARIABLE
    -513 DCX_INVALID_HANDLE
    -514 DCX_INVALID_LOAD_PARM
    -515 DCX_INVALID_MODE
    -516 DCX_INVALID_NAME
    -517 DCX_INVALID_PARAMETER
    -518 DCX_INVALID_POLLING
    -519 DCX_INVALID_RELEASE
    -520 DCX_INVALID_RESPONSE
    -521 DCX_INVALID_RESULT
    -522 DCX_INVALID_ROW_COL
    -523 DCX_INVALID_SEQNUM
    -524 DCX_INVALID_SERVICE
    -525 DCX_INVALID_TERM_ADDR
    -526 DCX_INVALID_TERM_EVENT
    -527 DCX_INVALID_TERMINAL_ID
    -528 DCX_INVALID_TERMSEQ
    -529 DCX_INVALID_TEXT_FILE
    -530 DCX_INVALID_TIMEOUT
    -531 DCX_INVALID_TONE_SPECIFIER
    -532 DCX_INVALID_TRANSID
    -533 DCX_LIST_TOO_LONG
    -534 DCX_STR_NOT_FOUND
    -535 DCX_STR_TOO_LONG
  

  The original TC was a 16-bit application which actually made 16-bit Dcc... API calls, the return codes it received were 16-bit return codes. Listed below are the 16-bit return codes and for each is listed the possible DCConnect return codes that map to it. Given a particular 16-bit return code, find the matching 32-bit return code(s) and use the DCConnect Technical Reference to get more details about the 32-bit return code(s).

    16-bit Return Code               32-bit Return Codes mapped to it
    -------------------              --------------------------------
    0  DCC_NO_ERROR                     0 DCX_NO_ERROR
    1  DCC_NOT_RUNNING                 -2 DCX_NOT_RUNNING
    2  DCC_NOT_RESPONDING            -308 DCX_NOT_RESPONDING
    3  DCC_OS2_ERROR                 -100 DCX_OS_ACCESS,
                                     -101 DCX_OS_GET_PROC,
                                     -103 DCX_OS_MSGPATH_CREATE,
                                     -104 DCX_OS_MSGPATH_OPEN,
                                     -105 DCX_OS_MSGPATH_READ,
                                     -106 DCX_OS_MSGPATH_WRITE,
                                     -107 DCX_OS_SEM,
                                     -108 DCX_OS_START_TASK,
                                     -109 DCX_CS2_NLS_ERROR,
                                       -1 DCX_INTERNAL_ERROR
    5  DCC_SHUTDOWN_IN_PROGRESS        -3 DCX_SHUTDOWN_IN_PROGRESS
    6  DCC_INVALID_PARAMETER         -206 DCX_READ_PENDING,
                                     -513 DCX_INVALID_HANDLE,
                                     -505 DCX_INVALID_DATALEN,
                                     -517 DCX_INVALID_PARAMETER,
                                     -504 DCX_INVALID_COMM_LOC,
                                     -503 DCX_INVALID_COMM_LINE,
                                     -525 DCX_INVALID_TERM_ADDR,
                                     -519 DCX_INVALID_RELEASE,
                                     -523 DCX_INVALID_SEQNUM,
                                     -528 DCX_INVALID_TERMSEQ,
                                     -530 DCX_INVALID_TIMEOUT
    7  DCC_DATA_TRUNCATED            -500 DCX_DATA_TRUNCATED
    8  DCC_LOGFILE_FULL                   No equivalent
    9  DCC_INVALID_FILE_FORMAT       -401 DCX_INVALID_FILE_FORMAT
    10 DCC_FILE_DOESNT_EXIST         -501 DCX_DOES_NOT_EXIST,
                                     -529 DCX_INVALID_TEXT_FILE
    11 DCC_INVALID_DATE_TIME         -506 DCX_INVALID_DATETIME
    12 DCC_INVALID_MODE              -310 DCX_TERM_IN_WRONG_STATE,
                                     -515 DCX_INVALID_MODE
    13 DCC_INVALID_ROW_COL           -522 DCX_INVALID_ROW_COL
    14 DCC_INVALID_ATTRIBUTE         -502 DCX_INVALID_ATTRIBUTE
    15 DCC_TRANSMIT_NAK              -301 DCX_BAD_STATUS,
                                     -309 DCX_REJECTED_DATA
    16 DCC_INVALID_FUNCTION_KEY      -526 DCX_INVALID_TERM_EVENT,
                                     -532 DCX_INVALID_TRANSID
    17 DCC_INVALID_TERMINAL_TYPE     -307 DCX_INVALID_TERMINAL_TYPE
    18 DCC_INVALID_RESPONSE          -520 DCX_INVALID_RESPONSE
    19 DCC_INVALID_TONE_SPECIFIER    -531 DCX_INVALID_TONE_SPECIFIER
    20 DCC_STR_NOT_FOUND             -534 DCX_STR_NOT_FOUND
    21 DCC_INVALID_GLOBAL_VARIABLE   -512 DCX_INVALID_GLOBAL_VARIABLE
    22 DCC_RESPONSE_INVALID          -204 DCX_NO_REQUEST_PENDING
    23 DCC_NETWORK_ERROR             -207 DCX_TIMEOUT,
                                     -302 DCX_BAD_TERMINAL
    24 DCC_ALLOC_FAILED              -102 DCX_OS_MEMORY
    25 DCC_INVALID_REFERENCE_NAME         No equivalent
    26 DCC_MAX_HANDLES               -203 DCX_NO_MORE_ROOM
    27 DCC_VALID_REQUEST_NO_RESPONSE -201 DCX_DID_NOT_REPLY
    28 DCC_INVALID_RESULT_CODE       -521 DCX_INVALID_RESULT
    29 DCC_DELETE_FAILED             -200 DCX_DELETE_FAILED
    30 DCC_INVALID_TERMINAL_ID       -527 DCX_INVALID_TERMINAL_ID
    31 DCC_INVALID_DURATION          -507 DCX_INVALID_DURATION
    32 DCC_INVALID_ERASE             -510 DCX_INVALID_ERASE
    35 DCC_RIC_TIME_SYNCH_ERROR           No equivalent
    36 DCC_RIC_DRIVER_OPEN_ERROR          No equivalent
    37 DCC_STR_TOO_LONG              -533 DCX_LIST_TOO_LONG,
                                     -535 DCX_STR_TOO_LONG
    38 DCC_EXCEEDS_PACKET_LEN             No equivalent
    39 DCC_LOGFILE_OPEN                   No equivalent
    40 DCC_LOGFILE_NOMEM                  No equivalent
    41 DCC_ERROR_PROC                     No equivalent
    43 DCC_TOOMANY_MONS                   No equivalent
    48 DCC_INVALID_NAME              -209 DCX_APPL_NOT_REGISTERED,
                                     -300 DCX_ACQUIRED,
                                     -511 DCX_INVALID_FILE,
                                     -516 DCX_INVALID_NAME
    49 DCC_FILE_ERROR                -202 DCX_FILE_LOADING,
                                     -400 DCX_FILE_ERROR
    50 DCC_NO_DATA                      6 DCX_NO_DATA,
                                     -210 DCX_READ_FAILED,
                                     -211 DCX_READ_SUCCESS_NO_REPLY
    52 DCC_INVALID_CLUSTER                No equivalent
    53 DCC_TERMINAL_LIST_TRUNCATED   -500 DCX_DATA_TRUNCATED
    54 DCC_FILE_LIST_TRUNCATED       -500 DCX_DATA_TRUNCATED
    55 DCC_CANCELLED                      No equivalent
    57 DCC_STARTUP_IN_PROGRESS         -4 DCX_STARTING_UP
    58 DCC_DOWNLOAD_IN_PROGRESS      -303 DCX_CMD_NOT_ALLOWED,
                                     -304 DCX_DOWNLOADING,
                                     -306 DCX_FLUSHING
    59 DCC_RESET_IN_PROGRESS              No equivalent
    60 DCC_TERM_BUF_NOT_EMPTY             No equivalent
    61 DCC_INVALID_FILE_NUMBER            No equivalent
    62 DCC_INVALID_RECORD_NUMBER          No equivalent
   
    -1 Unknown                            Anything else
   
  

  ---

  XIS011

  The file xx could not be opened, error = nn.

  The file exists but could not be opened. The file could be in exclusive use by another process. Restart the TC session with another file name, or cause the other process to release the file.

  ---

  XIS012

  Cannot allocate memory (module name, number of bytes).

  Heap space memory could not be allocated. Your system may be out of physical or virtual memory. Try shutting down other applications, and then restart the TC session.

  The message indicates which code module tried to allocate the memory and how many bytes it tried to allocate.

  ---

  XIS013

  Command file did not contain a script.

  Your command file did not contain any StartKey/StartVal/StartMatch/... commands or any commands within the Start / End limits.

  ---

  XIS014

  The script is too large.

  Your script commands will not compile into the 64KB segment maximum allowed for a script. Break your script into pieces, placing blocks of code into separate subroutines and then use the Call or CallSubroutine commands to branch to these subroutines.

  ---

  XIS015

  The command file contains too many labels.

  Your command file is allowed to have up to 500 labels defined. (See Label). Try to eliminate some labels (for example, set up a common label handle SQL errors from many scripts). You may need to split your script into two or more command files and run multiple sessions of TC.

  ---

  XIS016

  Session is starting.

  This is the TC session startup message.

  ---

  XIS017

  Session is ending.

  TC has been requested to shut down in response to a script file step, because of an error, or because Shutdown was selected.

  ---

  XIS018

  Compilation done.

  TC has completed compilation of your script command file.

  ---

  XIS019

  TC has released/replied to three consecutive transactions/requests.

  TC shuts down if it is forced to automatically release three transactions/requests in a row from DCConnect. It is assumed that this condition indicates an error condition, either in the use of the data collection terminals or in your script files. TC automatically releases/replies to a transaction/request if it encounters an EndKey / EndVal / EndMatch step without having processed the appropriate Release_Xact/Reply_To_Data_Request step, or if it receives a transaction/request for which it has no script to run.

  Correct by adding appropriate Release_Xact/Reply_To_Data_Request command(s) in your script and/or provide scripts for all incoming transactions or requests (or change the transaction mailbox configuration of DCConnect to avoid routing those transactions to the mailbox that the TC session is using).

  ---

  XIS020

  Unrecognized command.

  The compiler did not recognize the command on the line indicated. Check the spelling of the command.

  ---

  XIS021

  Syntax error in file xx on line ##: text

  The syntax of the referenced script file line is incorrect. Check the preceding error message for details of the cause of the syntax error.

  ---

  XIS022

  Logic error in file xx on line ##: text

  There is a logic error on the referenced script file line. Check the preceding error message for details of the cause of the error.

  ---

  XIS023

  Parameter error in file xx on line ##: text.

  There were no arguments provided between open and close parentheses, or the argument was invalid. There may be a preceding error message with more information.

  ---

  XIS024

  Label used more than once -> label.

  The label shown has already been used. Labels within a command script file must be unique.

  ---

  XIS025

  Label at line nnn in file file_name was not found: label

  There is a reference made to the specified label at line 'nnn' of the specified file, but that label reference could not be resolved because the actual label was not found any script file that was compiled. Make sure the label name is spelled correctly in both places and verify that all Begin_SQL / Begin_SQL2 / Begin_Select / Begin_Select2 and/or End_SQL / End_SQL2 / End_Select / End_Select2 pairs match up and are spelled correctly.

  ---

  XIS026

  Label not in a valid script: label name.

  The label shown was found outside a StartKey / EndKey, StartVal / EndVal, or StartMatch / EndMatch script definition. Labels must be placed only within a script definition.

  ---

  XIS027

  The script for internal script ID ## does not exist.

  The resolved address of a label could not be found. Contact IBM Data Collection Connection Support.

  ---

  XIS028

  Step ## for internal script ID ## does not exist.

  The resolved address of a label could not be found. Contact IBM Data Collection Connection Support.

  ---

  XIS029

  No opening parenthesis.

  The syntax of the command requires an opening parenthesis that encloses the left side of the arguments.

  ---

  XIS030

  Mismatch in number of opening and closing parentheses

  The TC command did not have a matching number of opening and closing parentheses. If the number does match, make sure any text is properly enclosed in double quotes and make sure any nearby comments start properly with double slash.

  ---

  XIS031

  Parameters are required for this command.

  There we no parameters found within the parentheses. Correct the syntax of the command.

  ---

  XIS032

  Unbalanced double quotes.

  A parameter used in the command arguments has no opening or no closing double quote marks, or otherwise has an odd number of double quote marks. Correct the quote marks of the string.

  ---

  XIS033

  No current StartKey, StartLogon, etc.

  The command being compiled is valid only within a StartKey / EndKey, StartVal / EndVal, or StartMatch / EndMatch script definition. Add a StartKey, StartVal, or StartMatch command, as appropriate for the operating mode, before the command. Add an EndKey or EndVal after the last command in the script definition.

  ---

  XIS034

  Still compiling script.

  The command being compiled is not valid within a StartKey / EndKey or StartVal / EndVal script definition. StartFunctionGroup / EndFunctionGroup are used to collect a StartKey / EndKey set into logical groups. As such, they are placed before and after the first and last lines, respectively, in the script command file section desired to serve the named DCConnect function group.

  ---

  XIS035

  Already compiled a script for key/event ID/val file name.

  Transaction Mode: If StartFunctionGroup / EndFunctionGroup commands are not used to logically group the StartKey scripts, a particular StartKey key/event ID (e.g. F1, F2, ...) can have only a single occurrence set in the entire set of script file. Either use a different key/event ID in the StartKey command, or use StartFunctionGroup / EndFunctionGroup to tell TC that the key/event IDs are to be used only for transactions originating from the particular DCConnect function groups named.

  Remote Validation Mode: You have duplicate validation file names used in the StartVal commands of your script. You can use a validation file name only once in the file/session.

  ---

  XIS036

  Not compiling a script.

  An EndKey, EndVal, or EndMatch command was encountered without there being a valid StartKey, StartVal, or StartMatch command in effect.

  ---

  XIS037

  Not compiling a StartLogon script.

  And EndLogon command was encountered without there being a valid StartLogon command in effect.

  ---

  XIS038

  Not compiling a StartLogoff script.

  And EndLogoff command was encountered without there being a valid StartLogoff command in effect.

  ---

  XIS039

  Not compiling a StartKey or StartVal script.

  An EndKey or EndVal command was encountered without there being a valid StartKey or StartVal command in effect.

  ---

  XIS040

  File name is not valid.

  The file name specified in the Log_Xact command is too long, has invalid characters, or has an invalid extension. Correct the file name in the script file(s) and restart the TC session.

  ---

  XIS041

  Unknown StartKey identifier.

  The key/event identifier in the StartKey command is not valid. Correct the identifier, selecting it from the list in StartKey in the command reference section.

  ---

  XIS042

  Unknown identifier.

  The keystroke identifier used in the Append / Set_UV_Kbd_Data or Append / Set or the Send_Host_Kbd_Data command was not recognized.

  ---

  XIS043

  Invalid defined name used for a parameter.

  The identifier (name) used to specify a part of the data transaction, another data area name, remote validation or interactive transaction response type, or interactive response BEEP or DURATION was invalid (see the DATA_PART parameter in the command reference section for Append_UV_Xact_Data or Setup_Insert_Field, the RESPONSE, BEEP, and DURATION parameters for Send_Term_IResp, and the RESPONSE for Send_Term_VResp).

  ---

  XIS044

  Message is too long or null.

  The message text parameter used in the command is too long to fit in the user variable or is null. By default user variables 1 to 240 can hold 235 characters and user variables 241-250 can hold 16383 characters. However the Define_UVs command may have been used to change these ranges. And the Define_Large_UV_Size command can be used to increase the number of characters that large user variables can hold.

  ---

  XIS045

  Label not found.

  There was no label or subroutine name found after the Goto or CallSubroutine command name. Check and correct the syntax of the command and restart the TC session.

  ---

  XIS046

  Label is too long.

  The label name is longer than the 31-character maximum limit.

  ---

  XIS047

  Releasing Transaction - Sequence Number: #####.

  An EndKey or EndMatch command has been reached and the user has not released the transaction with the command Release_Xact. TC has automatically released the transaction with the indicated sequence number, and the transaction has been logged to the TC2XACn.LOG transaction logfile.

  ---

  XIS048

  Transaction/request has already been released/replied to/forwarded.

  The Release_Xact/Reply_To_Data_Request/Forward_Data_Request command has already been issued for the current transaction/request. Correct the logic flow of your script.

  ---

  XIS049

  Error opening error log file.

  The drive containing the error log file may be full. Check for sufficient space, erasing some unnecessary files if required, or assign the log file to another drive.

  ---

  XIS050

  String is too long or 0-length.

  For the Send_To_Host, Send_Host_Kbd_Data, Append_UV_Kbd_Data (or Append) and Set_UV_Kbd_Data (or Set) commands the specified string was either 0 bytes long or was longer than the maximum allowed.

  ---

  XIS051

  Send Term Data string is too long.

  You cannot send more than 118 bytes to a data collection terminal's user variable.

  ---

  XIS052

  Row or Column parameter is invalid.

  Having only one of the row/col values set to 0 is not valid. Either both must be 0, or neither.

  ---

  XIS053

  No script is defined for this transaction.

  The transaction shown in the transaction data box at the top of the execution screen does not have a corresponding script (StartMatch/StartKey/StartVal) in the script command file. The transaction has been logged to the transaction log file and has been released. Either use DCConnect to remove the transaction ID of this transaction from routing groups associated with the mailbox that this TC session is using, or create a StartMatch/StartKey/StartVal script in the script command file for processing this transaction.

  ---

  XIS054

  Error writing error log file.

  The drive containing the error log file may be full. Check for sufficient space, erasing some unnecessary files if required, or assign the log file to another drive(**) (72).

  ---

  XIS055

  Error opening transaction log file.

  The drive containing the transaction log file may be full. Check for sufficient space, erasing some unnecessary files if required, or assign the log file to another drive(**) (72).

  ---

  XIS056

  Error writing transaction log file.

  The drive containing the transaction log file may be full. Check for sufficient space, erasing some unnecessary files if required, or assign the log file to another drive(**) (72).

  ---

  XIS057

  Error moving transaction log file pointer.

  The drive containing the transaction log file may be full. Check for sufficient space, erasing some unnecessary files if required, or assign the log file to another drive(**) (72).

  ---

  XIS058

  Log file name is not valid.

  The file name specified is too long, has invalid characters, or has an invalid extension. Correct the file name in the script file(s) and restart the TC session.

  ---

  XIS059

  Incomplete command found or too many closing parenthesis found.

  While parsing a script file, TC reached the end of the file or the end of its internal 1024 byte buffer and found that it did not have a complete command to process. TC considers a command to be incomplete if the number of opening and closing parentheses do not match; of course parentheses found within a constant string or a comment are ignored.

  ---

  XIS060

  Missing an EndLogoff command.

  A StartLogoff command was used without an ending EndLogoff command.

  ---

  XIS061

  Missing an EndKey/Logon/Logoff/Match/Interval/Time/... command.

  The compiler reached the end of the script command file without finding a closing EndKey, EndLogon, EndLogoff, EndMatch, EndInterval, EndTime command to finish the last script definition that was started.

  ---

  XIS062

  Check Screen data string is too long or null.

  You are checking for too much data on a Check_Screen command.

  ---

  XIS063

  Time value is not valid.

  No valid value for the time limit could be found in the command parameters.

  ---

  XIS064

  Length value is not valid.

  The length of data requested must be less than 16383.

  ---

  XIS065

  Check Screen label is too long or null.

  The label used in a Check... command was too long or was not found.

  ---

  XIS066

  Cannot use this command in a logon or logoff set.

  Some commands make sense only when dealing with a transaction or request from a terminal. In a logon/off script set, there is no transaction/request with which to work.

  ---

  XIS067

  User Variable number is not valid.

  The terminal user variable number is not valid. For the 7524 terminal and terminals running the DCConnect Client, the range of valid terminal user variables is 10-99. For the 7527 terminal, the user variable number can be in the range 10-19. For the 7526, the range can be 1-999, depending on how many user variables are defined. The valid range is always at least 1 to 3.

  ---

  XIS068

  Start value is not valid.

  The START offset value in the command must be less than 16383.

  ---

  XIS069

  Already in a cluster/function group.

  The StartCluster/StartFunctionGroup command cannot be used at this point because the previous StartCluster/StartFunctionGroup command has not be terminated with an EndCluster / EndFunctionGroup.

  ---

  XIS070

  Cluster/function group already defined.

  A function group with the name specified in the StartCluster/StartFunctionGroup command has already been defined.

  ---

  XIS071

  No cluster/function group defined.

  An EndCluster / EndFunctionGroup command was found without a previous StartCluster/StartFunctionGroup.

  ---

  XIS072

  Cluster/function group name is too long or null.

  The function group name specified in the StartCluster/StartFunctionGroup command was too long or was null. The function group name length limit is 31 characters.

  ---

  XIS073

  User variable length is too long.

  The user variable does not have sufficient space remaining in which to copy the data the command is attempting to append. Review the logic in your script to verify you are clearing the user variable as needed, or rearrange your commands to utilize more user variables. By default the maximum user variable size for user variables 1-240 is 235 characters and for user variables 241-250, the maximum size is 16383. However, these ranges may have been changed by the Define_UVs command.

  ---

  XIS074

  User variable name or number is not valid.

  TC was not able to determine a valid user variable name or number for one of the parameters.

  By default the valid user variables are UV1 through UV250. However the Define_UVs command may have been used to override the number of user variables. Either correct your script command file or increase the number of user variables by adding/changing the Define_UVs command to your script command file. Then restart the TC session.

  ---

  XIS075

  Too many clusters/function groups in use (up to nn are allowed).

  A single TC session can support up to the specified DCConnect function group names. If you need more than that, you must run multiple TC sessions on your system and configure multiple mailboxes, each receiving transactions from a group of nn or fewer function group names.

  ---

  XIS076

  Not compiling a subroutine script.

  An EndSubroutine command was found without an opening StartSubroutine call.

  ---

  XIS077

  Too many nested subroutines.

  You can nest up to 256 levels of subroutines (nesting means having one subroutine call another subroutine, which may in turn call yet another subroutine, and so forth). If you have more than 256 nested levels, you will need to eliminate some subroutines and replace them with in-line code in a higher calling subroutine.

  You may have accidentally coded a re-entrant loop, with subroutines calling themselves in a circular fashion.

  ---

  XIS078

  Subroutines stack error.

  The most likely cause of this error is that you have used a Goto to branch into a subroutine and then allowed the subroutine to execute through its ending EndSubroutine command. This will either cause an immediate XIS078 error, or will cause unpredictable and erroneous script execution. Make sure that subroutines are always called through CallSubroutine rather than using a Goto type of branching.

  ---

  XIS079

  No more space for subroutines (there are at least nnnn defined)

  As of 3/23/2005 you can have over 6000 subroutines and StartMatch scripts combined. (Earlier limits were 250 (fix packs D-F for version 1.40) and 125 (prior to fix pack D for version 1.40)).

  One way to reduce the number of subroutines is to combine any that are similar and add more parameter to handle the differences. Or you could split your scripts between two or more TC sessions so the number of subroutines required for one sessions can be reduced.

  ---

  XIS080

  No more space for StartMatch scripts (there are at least nnnn defined).

  As of 3/23/2005 you can have over 6000 subroutines and StartMatch scripts combined. (Prior to this up to 125 StartMatch scripts were allowed).

  You will need to split your scripts between two or more TC sessions so that the number of StartMatch scripts handled by each TC session can be reduced.

  ---

  XIS081

  Not compiling a StartMatch script.

  An EndMatch command was found without having an opening StartMatch command. Add a valid StartMatch command prior to the EndMatch.

  ---

  XIS082

  The Data Collection program is not running yet. Re-trying every five seconds....

  TC has been started and is now waiting for DCConnect to start up. It will retry every 5 seconds, and will do this indefinitely.

  ---

  XIS083

  Connected to database (name) running on (database system).

  Informational message indicating that TC has completed its connection to the database you specified on the command line, and this database is resident on the indicated database system (for example, DB2, DB2/NT, SQL/400, Microsoft SQL Server, Oracle 8.0, and so forth). When using ODBC, this database system (or DBMS name) should match one of the ALIAS strings in DBTYPE.INI (with the use of wild card characters possible in the ALIAS string). See DBTYPE.INI.

  ---

  XIS084

  Restarting database -- This may take some time....

  TC has received an error code from the database system indicating a restart of the database is required. TC is automatically attempting this restart.

  ---

  XIS085

  Connecting to database (name).

  TC is currently attempting to connect to the database named on your command line or in your script command file(s).

  ---

  XIS086

  Forcing COMMIT as specified by RC action or because script has completed.

  TC forced a commit of outstanding database operations for one of two reasons:

  • TC has finished processing a script and some outstanding database work has not been committed. This will also be done for the script command Done.

  • A database error has occurred and the default action defined for this error (in the appropriate RC_*.INI file) specifies FORCE_COMMIT_RETRY. For example, in RC_DB2.INI, the native code -912 and the SQLSTATE 57033 (OE MAX LOCKS REACHED) are assigned the action FORCE_COMMIT_RETRY.

  After performing the COMMIT, TC re-executes all of the commands since the beginning of the currently executing script or since the last Commit_Changes command in that script.

  If using DB2 and the OE MAX LOCKS REACHED error occurred, it is recommended that you consider increasing the database configuration parameter (locklist) to allow more lock space.

  ---

  XIS087

  Invalid field type specified for column.

  The field type specified in the command was not one of the valid choices of CHARACTER, NUMERIC, TIME, DATE, TIMESTAMP.

  ---

  XIS088

  DATE values with no delimiters must be in YYMMDD form.

  Fields typed as DATE must be in YYMMDD form. If time/date delimiters are already supplied in the data record, TC will not perform date formatting and will pass your data record to the database as-is.

  ---

  XIS089

  TIME values with no delimiters must be in HHMM or HHMMSS form

  Fields typed as TIME must be in HHMM or HHMMSS form. If time/date delimiters are already supplied in the data recrod, then TC will not perform time formatting and will pass your data record to the database as-is.

  ---

  XIS090

  TIMESTAMP values must be in YYMMDDHHMMSS form

  Fields typed as TIMESTAMP must be in YYMMDDHHMMSS form. If time/date delimiters are already supplied in the data record, then TC will not perform timestamp formatting and will pass your data record to the database as-is.

  ---

  XIS091

  Binding database (name) with package (file).

  Information message indicating that TC has received a return code from the database indicating that binding must be performed to create a package (formerly called access plan in DBM). TC is now automatically attempting this bind function.

  You can manually perform the bind operation prior to running TC if binding requires special administrator access.

  This message can only occur if TC is connecting to DB2 directly - instead of using the ODBC interface.

  ---

  XIS093

  Forcing COMMIT due to ending of script with SQL not committed.

  Changes were made to the database during execution of the script, but neither the Rollback_Changes or Commit_Changes command was used to remove the changes or make them permanent. TC assumes that you would want the changes made permanent, and has done so for you.

  This also removes row locks put in place by SELECT statements, even when no changes (UPDATE or INSERT) were made.

  ---

  XIS094

  SQL Error: native code = (xx), SQLSTATE = (sss).

  The SQL statement created by from the script has resulted in an error code from the database. Additional data about the error is in the TC2ERRn.LOG error log file for this session.

  ---

  XIS095

  Error trying to get message text for error. Return code is return code, SQLSTATE=state error

  TC was attempting to get message text for an SQL error that occurred to that it could write it to the TC2ERRn.LOG file, but encountered the error noted from database driver.

  ---

  XIS096

  Retrying last SQL command due to recoverable error: Native rc = native return code, SQLSTATE=state error

  TC received an error from the database driver considered to be recoverable by automatic means. TC has attempted the recovery method, and is now re-trying your script command steps that were affected.

  ---

  XIS097

  Re-doing SQL since last COMMIT due to native error native return code, SQLSTATE=state error

  TC received an error from the database driver that is considered to be recoverable by automatic means. TC has attempted the recovery method, and is now re-trying the script commands executed since the last database COMMIT (which may be from the start of the current script, or since any COMMIT performed during the script).

  ---

  XIS098

  Result column number ## from SELECT is out of range.

  An Append_UV_Select_Data command attempted to append from a report column that does not exist. The results from a SELECT statement will be in a number of columns, with the number of columns dictated by number of column names or column operations specified in your SQL SELECT statement. This range is from 1 to 255 columns maximum, and is checked at compile-time. However, the compiler does not count how many columns or column functions you requested (through your Select_Column command calls or in free-form SQL), so at run-time, the column number requested is verified against the actual number of columns which you requested. To correct, examine your Select_Column calls or your free-form SQL to determine the correct column number for use the the Append_UV_Select_Data command.

  ---

  XIS099

  Unrecognized command type found in compiled script.

  The internal command ID found in a compile script was not valid. Contact IBM Data Collection Connection Support.

  ---

  XIS100

  Fetch attempted with obsoleted SELECT statement.

  A database INSERT, UPDATE, COMMIT, or ROLLBACK has been executed since the last SELECT statement was executed, thereby obsoleting the data area in which the SELECT statements result data was stored. There is no valid data to fetch. Change your script command file to perform all needed Fetches prior to issuing any INSERT, UPDATE, COMMIT, or ROLLBACK statements.

  ---

  XIS101

  String sent to the Data Collection program was too long.

  A string sent to DCConnect by TC on behalf of a script command was too long. The length of a user variable string may exceed the maximum allowed by DCConnect (usually 118 bytes).

  ---

  XIS102

  No valid SELECT data is available for Append_UV_Select_Data.

  An attempt to append to a user variable from the results of a SELECT statement is invalid because no SELECT statement has been executed since the beginning of the script or since the last INSERT, UPDATE, COMMIT, or ROLLBACK.

  ---

  XIS103

  The SQL statement is too long to fit in internal buffers.

  Your SQL statement was too long to fit in TC's internal 4,000-character buffers. You can do one of two things:

  • Use the TC command SQL_Buffer_Size to increase the size of TC's internal buffers. See SQL_Buffer_Size

  • Reformulate your SQL statement to be shorter in length. This may include breaking it into several statements, making column names shorter, and so forth.

  ---

  XIS104

  The number in a :UVnn reference is invalid.

  In a free-form SQL statement, an invalid user variable was referenced. Valid references are :UV1 to :UV250 or whatever maximum is defined by the Define_UVs command.

  ---

  XIS105

  Could not create thread.

  If this error occurs frequently, contact your IBM support representative.

  ---

  XIS106

  Could not create pipe pipe name, rc = operating system error value

  TC had the specified error trying to create the specified internal pipe. If this error occurs frequently contact your IBM support representative.

  ---

  XIS107

  (error message)

  This error number comes from either the separate thread that asynchronously handles sending of user variable text to data collection terminals (ASYNCHronous usage) or directly from the main thread when sending SYNCHronously.

  Some errors (for example, a terminal not responding) are treated as non-fatal errors, and a warning is shown only on the screen.

  Various errors may be encountered in doing this task. To determine which Send_Term_UV_Data command failed, you may need to have the DCConnect monitor running to record the Command I (the underlying low-level command that transfers data to a terminal user variable) data transactions to the terminal so you can see which Command I was the last to make it to the terminal. The error message text can be:

  • "Pipe DosRead error": Contact IBM Data Collection Connection Support

  • "Pipe synchronization error": Contact IBM Data Collection Connection Support

  • "Invalid user variable number": The terminal user variable that was being set was invalid for that terminal.

  • "Invalid terminalID: ": Contact IBM Data Collection Connection Support

  • "String too long: ": The string being sent to the DCT was too long

  • "16-bit error number = (number)": DCConnect returned an error. See the DCConnect error number list given in this table for error XIS010.

  ---

  XIS108

  Too many On_Error_Goto conditions in effect.

  There is a limit of 15 on-error conditions that can be in effect at one time. Make some space in the list by NULLing some unneeded conditions.

  ---

  XIS109

  Too many references to labels are used.

  You can have up to 1800 references to labels in your set of command script files. This includes all instances of the various commands that list a label for conditional branching, but does not include the actual label definitions themselves (there is a limit of 256 individual labels in the file). You may need to split your set of command files into 2 or more sets of files and run multiple TC sessions - one for each set.

  ---

  XIS110

  Delimited transaction field not found in data.

  The delimited transaction data field requested was not found in the transaction data. You must coordinate how the transaction program on the DCT creates the transaction record with how the script command file attempts to access the resulting transaction. The transaction program may need to add semi-colons to delimit empty data fields.

  Delimited field number 1 starts at the first character of the data area of the transaction and continues up to the first semi-colon delimiter. There must also be a semi-colon at the end of the last field to separate it from the timestamp information.

  ---

  XIS111

  '.VAL' extension not found on validation file name

  You must specify the.VAL extension on the validation file names used in the StartVal commands.

  ---

  XIS112

  This DEMO version has just ignored a valid transaction.

  The free demonstration version of TC will arbitrarily discard 1% of your incoming transactions; it is not useful in production environments.

  ---

  XIS113

  Command is not valid for REMOTE_VALIDATION or DATA_REQUEST mode.

  The Xact_Age, Log_Xact, StartCluster, and EndCluster commands cannot be used when TC is operating in REMOTE_VALIDATION or DATA_REQUEST mode.

  ---

  XIS114

  Log_Data file open MODE is not valid.

  The command Log_Data only accepts a file-open mode of APPEND or OVERWRITE.

  ---

  XIS115

  Log_Data file could not be opened or used.

  The data file name may be locked by another process. Close that process or change the access mode of this file.

  ---

  XIS116

  Invalid IF/WHILE statement syntax: code from script

  The syntax of the specified If or While statement is invalid. See If or While (Do...While) for details.

  ---

  XIS117

  Expected closing '}' before EndKey / EndVal / EndMatch / End... command.

  There were more opening braces { between the StartKey/StartVal/StartMatch/Start... and the EndKey / EndVal / EndMatch / End... than there were closing braces. Check the matching of your brace sets.

  ---

  XIS118

  Too many command levels created by If statements.

  You can have up to 50 nested levels of { } braces. Simplify the construction of your scripts to eliminate nesting of braces.

  ---

  XIS119

  An extraneous closing '}' was found.

  There were more closing braces } between the StartKey/StartVal/StartMatch and the line in error than there were opening braces. Check the matching of your brace sets.

  This error can also be caused by having an opening brace { which does not have an "If" or "Else" statement immediately before it. For example, you may not do this:

   
    If ( UV1 == "abc" )
      Command A
     {
      Command B
      Command C
     }
   
  

  ---

  XIS120

  A required BIND file could not be found.

  Make sure that either:

  1. TC is started from the same directory in which the bind file (TCDB2.BND) is located.
  2. The TC2 environment variable is set to the proper directory where the file is located.

  ---

  XIS121

  The path to the BIND files could not be found.

  The path specified in the TC2 environment variable could not be found. Check your CONFIG.SYS file.

  ---

  XIS122

  File I/O problem nnn encountered while opening BIND file.

  TC tried to open a.BND file (bind file) and received an operating system error. The error number reported in the message above could be one of the following:

    4         ERROR_TOO_MANY_OPEN_FILES
    5         ERROR_ACCESS_DENIED
    12        ERROR_INVALID_ACCESS
    26        ERROR_NOT_DOS_DISK
    32        ERROR_SHARING_VIOLATION
    36        ERROR_SHARING_BUFFER_EXCEEDED
    82        ERROR_CANNOT_MAKE
    87        ERROR_INVALID_PARAMETER
    99        ERROR_DEVICE_IN_USE
    108       ERROR_DRIVE_LOCKED
    110       ERROR_OPEN_FAILED
    112       ERROR_DISK_FULL
    206       ERROR_FILENAME_EXCED_RANGE
    231       ERROR_PIPE_BUSY
  

  ---

  XIS123

  Specified start (sss) / length (lll) combination goes past the length (nnn) of the actual data

  The starting location within the data part is located beyond the end of that data part, or the length specified could not be fulfilled considering the amount of data available and the requested starting position. No data was retrieved if the start was beyond the end of the data, or the data was truncated to only the amount available after the start location.

  Check your transaction format provided from the DCT as compared to your script, and adjust the appropriate commands to make the data compatible with the processing.

  ---

  XIS124

  Divide-by-zero error in UV_Math statement.

  The constant value or the current value of the user variable to be used as the divisor is 0. This is an illegal mathematical operation. Make sure the divisor is non-zero.

  ---

  XIS125

  Invalid UV_Math arithmetic operator.

  The arithmetic operator for the UV_Math function must be one of the set +,-,*,/, or =.

  ---

  XIS126

  User variable file could not be opened or used.

  The file used for storing terminal-specific user variables could not be opened, or could not be properly read from or written to. Ensure that there is sufficient space on the disk to hold the files. If a new version of TC was just installed, you may need to delete the UVDATA*.* files that were created with an older version of TC.

  ---

  XIS127

  CM Session was already starting.

  CM session was already starting when Cycle_Session tried to re-start the session. Contact IBM.

  ---

  XIS128

  CM Session was already stopping.

  CM session was already stopping when Cycle_Session tried to stop the session. Contact IBM.

  ---

  XIS129

  CM Session was not configured in PCOMM.

  CM session used by Cycle_Session was not configured in PCOMM. You may have specified the wrong emulation type on the Cycle_Session command when compared to the emulation being run on the PCOMM session. If this is not the case, contact IBM.

  ---

  XIS130

  PCOMM Internal error.

  Contact IBM.

  ---

  XIS131

  Invalid PCOMM service requested.

  You may have specified the wrong emulation type on the Cycle_Session command when compared to the emulation being run on the PCOMM session. If this is not the case, contact IBM.

  ---

  XIS132

  PCOMM Kernel is inactive.

  Contact IBM.

  ---

  XIS133

  CM Session was already started.

  Contact IBM.

  ---

  XIS134

  CM Session unable to start.

  You may have specified the wrong emulation type on the Cycle_Session command when compared to the emulation being run on the PCOMM session. If this is not the case, contact IBM.

  ---

  XIS135

  CM Session did not stop.

  Contact IBM.

  ---

  XIS136

  Bad emulation session type specified.

  Specify either 5250 or 3270 as the parameter for Cycle_Session.

  ---

  XIS137

  Logfile is full -- retrying every 0.5 seconds.

  Your script is generating transactions that are written to a DCConnect mailbox. It may be the case that no currently running application is reading and processing the transactions from that mailbox. In this case start the other application.

  If an application is reading the mailbox but is just doing so slowly, consider increasing the capacity of that mailbox using the DCConnect User Interface.

  If the mailbox contains transactions that are no longer needed, use the DCConnect User Interface to clear the transactions out of the mailbox.

  ---

  XIS138

  Warning -- Control code (@x) found in string.

  An EHLLAPI control code sequence has been found in the data string Send_To_Host was transmitting to the host screen. This non-fatal error reminds you that control codes and text/numeric data should not be mixed in a user variable or string. See Send_To_Host

  ---

  XIS139

  Bad cursor movement option specified.

  The only valid cursor movement types are: NONE, START, and END.

  ---

  XIS140

  Not compiling a StartTimeout script.

  EndTimeout encountered without a StartTimeout beginning the script.

  ---

  XIS141

  Invalid color, highlight, or FOREGROUND/BACKGROUND.

  See the commands Check_Color and Check_Highlight for the lists of valid color, highlight, and screen area names.

  ---

  XIS142

  Warning: DB could not be connected.

  TC is running with the option Run_Without_Connect and has just unsuccessfully attempted to connect to the database. It will attempt again each minute.

  ---

  XIS143

  Not compiling a StartInterval script.

  An EndInterval command was encountered without an opening StartInterval.

  ---

  XIS144

  Not compiling a StartTime script.

  An EndTime command was encountered without an opening StartTime.

  ---

  XIS145

  WHILE command has no matching DO command.

  The While command can only be used in conjunction with a matching Do command:

    Do
      (some command)
    While ( some condition)
  

  or

    Do
     {
      (some command)
       ...
      (some other command)
     }
    While ( some condition)
  

  ---

  XIS146

  No closing End_SQL command found.

  The end of the script was found and no closing End_SQL / End_SQL2 / End_Select / End_Select2 was found to match an opening Begin_SQL / Begin_SQL2 / Begin_Select / Begin_Select2.

  ---

  XIS147

  Unknown command line flag: (flag).

  The text after the / on a startup command line flag is not valid.

  ---

  XIS148

  Too many levels of imbedded source files.

  Imbed commands can only be nested up to 5 levels deep. Simplify your file imbed structure.

  ---

  XIS149

  UVnn has already been named: first name used

  The specified user variable number nn used in the Name_UV command has already been assigned the specified name. One of these two Name_UV commands must be removed or changed.

  ---

  XIS150

  The name used is a reserved word.

  The name being assigned to a user variable is already used by the system as the name of another data part. Use a different name.

  ---

  XIS151

  UV name storage exceeded.

  The total length of all of your user variable names exceeds 64KB. Shorten the names to allow more names to be used.

  ---

  XIS152

  File submitted as VAL file had invalid format.

  Refer to the DCConnect Technical Guide for details of the required format for files that are to be submitted as validation files.

  ---

  XIS153

  Data Collection program Network Error -- command to terminal failed.

  ---

  XIS154

  Unknown event reported. Contact IBM.

  An unknown type of event was encountered.

  ---

  XIS155

  Invalid window setting used.

  See Set_Emulator_Window for the allowed values.

  ---

  XIS156

  Maximum length for a real number is 234 characters

  When using the REAL_NUM type for the Format_UV command, the total length specified cannot exceed 234 characters.

  ---

  XIS157

  Maximum fractional part of a real number is 232 digits

  When using the REAL_NUM type for the Format_UV command, the number of digits to the right of the decimal point cannot exceed 232 bytes - two less than the total maximum.

  ---

  XIS158

  Sign indication parameter for a REAL_NUM must be YES or NO

  When using the REAL_NUM type for the Format_UV command, the last parameter must be YES or NO to indicate whether or not the number is allowed to be signed.

  ---

  XIS159

  Attempt to format invalid real number: ###.##

  The real number could not be formatted because it either exceeded the whole/fractional length specified or it was not a valid real number. Examples of invalid real numbers are those with multiple decimal points, multiple signs, spaces in the middle, ...

  ---

  XIS160

  Real number max length: ## does not match length of UVnn: ##

  When using the Format_UV()'s REAL_NUM option, the length specified must exactly match the length of the user variable being formatted in order for the result to be correct.

  ---

  XIS161

  The reference to UVnn exceeds the maximum: UVxx

  Therre is a reference to a user variable number (UVnn) that is higher than the maximum user variable defined (UVxx). By default, the maximum user variable is UV250. But this can be changed via the Define_UVs command.

  ---

  XIS163

  The API nnn is not supported by the DCC/2 16-bit runtime

  Several of the TC commands map to DCC/2 or DCConnect APIs. Older versions of DCC/2 did not support all of those APIs that can be issued by the TC application. The following commands/APIs not supported by the DCC/2 16-bit runtime:

  • Get_Term_UV_Data ... DccGetTermUserVariable
  • Send_Term_UV_Data when more than user variable is specified... DccSetNTermUserVariables
  • Make_Data_Request ... DccRequestData
  • Reply_To_Data_Request ... DccReplyDataRequest
  • Running in DATA_REQUEST mode is not supported.

  ---

  XIS164

  The API API name is supported only by DCConnect

  All DATA_REQUEST functions and commands are supported only when running with DCConnect. These include:

  • Make_Data_Request ... DccRequestData
  • Reply_To_Data_Request ... DccReplyDataRequest
  • Running in DATA_REQUEST mode

  ---

  XIS165

  Nested Begin_SQL statement found; Possible misspelled End_SQL

  A second Begin_SQL / Begin_SQL2 / Begin_Select / Begin_Select2 statement was found before the End_SQL / End_SQL2 / End_Select / End_Select2 statement was found for the last Begin_xxx statement. Make sure all End_xxx statements are present and are properly spelled.

  ---

  XIS166

  Line nn: export (mailbox) must be defined before command at line nn in the script xxx

  If the mailbox is defined in the script, it must be defined before any script command that is dependent on whether or not the TC session will be running in REMOTE_VALIDATION mode or DATA_REQUEST mode. The mailbox command must be specified before the line number suggested in this message.

  ---

  XIS167

  Line nn: export (mailbox) already defined from command line or elsewhere in script

  A mailbox statement was found at the specified line. The mailbox was already defined on the command line or somewhere else in the script. The mailbox can be defined once only, either on the command line or in the script.

  ---

  XIS168

  TC command not valid in DATA_REQUEST mode

  In addition to the commands that are not valid in both DATA_REQUEST mode and REMOTE_VALIDATION mode, the StartKey / EndKey commands are not allowed in DATA_REQUEST mode.

  ---

  XIS169

  Line nn: application already defined from command line or elsewhere in script.

  An application statement was found at the specified line. The application was already defined on the command line or somewhere else in the script. The application name can be defined only once - either on the command line or in the script.

  ---

  XIS170

  An application name must be defined if handling data requests

  When in DATA_REQUEST mode, you must specify the application name. This can be done on the command line or using the Application command anywhere in the script file.

  ---

  XIS171

  This command is only valid in DATA_REQUEST mode

  The command Reply_To_Data_Request is only valid when running in DATA_REQUEST mode.

  ---

  XIS172

  Sending default reply to data request originator: xxx

  An EndMatch command has been reached and the script has not yet replied to the current data request with the command Reply_To_Data_Request. TC sent a default (empty) reply to the originator of the request. The request has been logged to the TC2XACn.LOG logfile.

  ---

  XIS173

  'DONE()' cannot be in a subroutine

  The Done command can only be used in a StartMatch or StartKey script. To leave a subroutine early, just use the Return() command.

  ---

  XIS174

  There is no data file open for read.

  This message is given if the Append_UV_File_Data command is used without first calling the Open_File_Data command.

  ---

  XIS175

  Line nn: Large UV size must be in the range xxx to yyy bytes

  In the command Define_Large_UV_Size, the size specified is not within the valid range xxx-yyy in the message.

  ---

  XIS176

  Waiting nn seconds for xx thread(s) to end ...

  Informational message given at shutdown when one thread of TC has initiated a shutdown and is waiting for the other threads to end themselves.

  ---

  XIS177

  Line nn: Can't redefine number of user variables or size of user variables after one is referenced,

  This message is given if the Define_UVs command or Define_Large_UV_Size command is used after any user variable is referenced by any script command. If the Define_UVs command or Define_Large_UV_Size command is to be used, ensure that it is one of the first commands performed in the top-level script file, before any other file is imbedded.

  ---

  XIS178

  Line nn: Minimum # of user variables is 20 and total # must be > # of big ones

  Invalid parameters were provided in the Define_UVs command. The first parameter, which specifies the total number of user variables, must be 20 or greater. The second parameter, which specifies how many of the total will be the large type of user variables (16383 bytes), must be less than or equal to the first parameter.

  ---

  XIS200

  The UV name 'xyz' has already been used for UV nn (names are case insensitive)

  This error is given if a Name_UV command provides a name for a user variable that has already been used. The case of the name does not matter. Therefore the lower case equivalent of an all upper case name is considered a matching name.

  ---

  XIS201

  Couldn't create XML BOD for xxx - maximum number of messages already exist

  This generally happens when there is a leak of XML handles in the sript. Verify that each generated handle (either through an XML_CreateBOD or XML_SendBOD) is passed to XMLCleanup to release it. In general, the handle value should be 1 or 2 and in some cases 3. If it is ever high than 3, it is likely that there is a leak which should be investigated.

  ---

  XIS202

  Bad XML handle generated or passed

  The XML handle is invalid. This is probably because the XML_CreateBOD or XML_SendBOD command failed and returned a handle value of zero.

  ---

  XIS203

  Unable to process XML command

  General failure processing an XML command. This is a serious internal error indicating a problem with the underlying XML message manipulation routines. This error should be reported to technical support.

  ---

  XIS204

  Message structure does not match expected structure

  The input XML message does not conform to the BOD standard. This error happens when processing a generic XML message with BOD specific calls. Use the generic XML calls instead.

  ---

  XIS205

  XML send function already set

  Only one call to XML_Sender can exist in the script. Please check the main script and all imbedded scripts for additional instances of the XML_Sender command.

  ---

  XIS206

  Could not find script to process the current transaction/request

  This message is given if TC does not find an appropriate StartMatch, StartKey or StartVal script to process an incoming transaction, validation request or data request. To help figure out what is going on, turn on the trace and regenerate the transaction/request. The trace file will show this message preceded by information about the transaction/request that could not be processed.

  ---

  XIS207

  The application name xxx is already in use by another program

  When a TC session that is running in data request mode attempts to hook up with DCConnect using the API DcxOpenRequestHandler, this message is given if the return code received from DCConnect is DCX_INVALID_MODE. This indicates the specified application name is already being used by another request handler (TC session or other application). The Application command or equivalent command line parameter should be changed to use a unique application name.

  ---

  XIS208

  The database operation was successful with minor errors. DB Message=xxx

  The database operation return an error code that was assigned the action LOG_RETURN_NO_ERROR in the active RC_*.INI files. LOG_RETURN_NO_ERROR is also the default action that TC takes if an error code is not found in any of the active RC_*.INI files. TC will continue processing the current script but has logged this message to inform you of the minor error that occurred. Whether or not additional action is required must be determined by the user after inspecting the DB Message specified at the end of this message.

  For more information about TC's handling of error codes returned from database operations, please see How TC Handles SQL Errors.

  ---

  XIS209

  The On Error string 'xxx' was not defined in the scripts or in the appropriate RC_*.INI files

  While compiling an On_Error_Goto command, TC found that the specified On Error string was not defined in any of the RC_*.INI files and it was not defined using the Define_On_Error_String command. TC must find the definition for this On Error string in order to be able to associate a native code value and/or SQLSTATE value to this On_Error_Goto command.

  If you intended to use the Define_On_Error_String command to define this On Error string, you must define it before its first use in any On_Error_Goto command. For more information please see On Error Strings.

  ---

  XIS210

  Connection operation %s was successful with minor errors. SQLSTATE=sss, Native rc=rrr, ODBC Message=mmm

  When TC successfully performed the specified connection operation using ODBC, it received an error code from the ODBC driver indicating there were minor errors with the operation. TC logs this message to let the user know what occurred. Whether or not additional action is required must be determined by the user after inspecting the ODBC Message specified at the end of this message.

  This message might be logged after TC internally performs any of the following operations:

  • Allocating an environment handle using SQLAllocHandle

  • Calling SQLSetEnvAttr to set SQL_ATTR_ODBC_VERSION to SQL_OV_ODBC3

  • Allocating a connection handle using SQLAllocHandle

  • Calling SQLSetConnectOption to set SQL_AUTOCOMMIT to SQL_AUTOCOMMIT_OFF

  • Connecting to the database using SQLDriverConnect

  • Allocating a statement handle using SQLAllocHandle

  ---

  XIS211

  Connection operation %s failed. SQLSTATE=sss, Native rc=rrr, ODBC Msg=mmm

  TC was unsuccessful performing the connection operation specified for the reason indicated by the SQLSTATE, Native rc and ODBC message specified in this message. Please refer to the documentation that came with database software in order to get more information and to determine what should be done to resolve the problem.

  This message could be given for any of the situations described above for message XIS210. If the error occurred when trying to allocate an environment handle or set an environment option, TC will terminate no matter what.

  If the error occurred when trying to allocate a connection handle or set a connection option, TC will terminate unless Run_Without_Connect is in effect.

  If the error occurred on the SQLDriverConnect call, TC will terminate after logging this message unless one of the following SQLSTATE values was returned:

  • 08001 = Client unable to establish connection

  • 08002 = Connection name in use

  • 08004 = Server rejected the connection

  • 08S01 = Communication link failure

  • HYT00 = Timeout expired

  • HYT01 = Connection timeout expired

  For the above SQLSTATE values, TC will delay 2 seconds and try again unless Run_Without_Connect is in effect. If Run_Without_Connect is in effect, TC waits a minute before retrying.

  If the error occurred when allocating a statement handle it is treated just as a non-fatal error on a SQLDriverConnect call - except that the connection is closed an reopened before trying to allocate the statement handle again.

  ---

  XIS212

  Failed to get ODBC environment handle; no additional info available

  While attempting to establish an ODBC database connection TC encountered an error with one of the calls used to get an environment handle. Because this is the highest level handle obtained and it failed to be allocated, there is no mechanism available to get more information.

  ---

  XIS213

  Action table ini file xxx does not contain any valid entries.

  TC logs this message when there was an error trying to process the specified .INI file or if it found no valid action entries in the specified file. If the specified file in the message is RC_*.INI then there should be a previous message that gives more information about an error encountered while processing the file.

  ---

  XIS215

  The On Error Go To value 'xxx' is not a valid OE string, SQLSTATE code or native code.

  While processing an On_Error_Goto command, TC determined that the first parameter was not valid. The first parameter can be one of the following:

  • An On predefined On Error String - which must start with 'OE'

  • An SQLSTATE value, which must start with 'SQL' and be followed by the up-to-5 character SQLSTATE string.

  • A numeric native code value (positive or negative).

  For more information about how TC handles SQL errors and how they can be specified in the On_Error_Goto command, please see How TC Handles SQL Errors.

  ---

  XIS216

  Run_Without_Connect is in effect and there is currently no database connection

  This message is given as the SQL error message for any database operation that is attempted in Run_Without_Connect mode between the time that the database connection is closed due to an error and the time that the connection is successfully reestablished by TC's database reconnect thread - which waits a minute between reconnect attempts.

  ---

  XIS217

  Invalid statement found in DBTYPE.INI: xxx

  While processing the DBTYPE.INI file TC encountered the specified invalid statement in the file. For more information about this file, please see DBTYPE.INI.

  ---

  XIS218

  Database type name too long in DBTYPE.INI: xxx

  The database type name that is enclosed in square brackets cannot be longer than 64 characters.

  ---

  XIS219

  The DBTYPE can only use =, ==, <>, != for a comparison and can only be compared to one of the types found in DBTYPE.INI.

  When DBTYPE is used in an IF statement, it must be compared to one of the valid database types that are found in DBTYPE.INI (those names that are enclosed in the sqaure brackets). In addition, the comparison must be one of equality ( == or = ) or inequality ( <> or != ).

  For more information about the format of DBTYPE.INI please see DBTYPE.INI.

  For general instructions about using the DBTYPE data part in the If command please see Using DBTYPE in an If Command.

  ---

  XIS220

  The DBMS name returned by the ODBC driver, 'xxx', does not match any alias in DBTYPE.INI.

  TC was attempting to match the DBMS name returned from the ODBC driver with one of the ALIAS strings found in DBTYPE.INI but it did not find a match. TC will do this when it needs to find out some information that is specific to the current database type such as the date or time separator.

  The problem may be that the database type is not defined in DBTYPE.INI at all or it may just be that the current ALIAS definitions are not set up properly for the existing database type that is correct.

  Instructions for adding a new database type to DBTYPE.INI can be found in Adding Support for Other Database types to DBTYPE.INI.

  While this section describes adding a brand new type to the file, these instructions also include steps for determining what DBMS name is being returned by the ODBC driver so that you can verify/correct the existing ALIAS definitions.

  ---

  XIS221

  Too many local user variables declared; maximum is 1024.

  During compile, the combined count of passed parameters to the routine and Declared local user variables has exceeded the maximum limit.

  During execution, the path through the code has resulted in a quantity fo Declared local user variables combined with the 'call stack' of passed parameters from each level to the next such that the quantity exceed the maximum limit.

  ---

  XIS222

  At line nnn of file name, Call->Sub parameter count mismatch. Call to: subroutine name

  The number of parameters passed by a Call / CallSubroutine command does not match the number of parameters required by the subroutine that is being called.

  ---

  XIS223

  At line nnn of file name, Call->StartSubroutine or branch/CallSubroutine->Sub mismatch. Call to: subroutine label

  The Call command can only be used to call a subroutine that is defined with the Sub command, unless there are no parameters. Similarly the CallSubroutine command can only be used to call a subroutine that is defined with the StartSubroutine command, unless there are no parameters. It is also invalid to specify a subroutine label as an error label for commands such as PeformFetch or Initiate_Term_Event, if that subroutine was defined using the Sub command and that subroutine has one or more parameters.

  ---

  XIS224

  The DBTYPE cannot be defined more than once and it must be defined before any On_Error_Goto commands.

  The DBTYPE command can only be used once in the scripts, including on the command line. In addition, the DBTYPE must be defined before any On_Error_Goto command that references an On Error String or an SQLSTATE value because TC looks up those values in its action table that was read from either RC_DB2.INI or RC_ODBC.INI. And TC needs to know the DBTYPE to determine which of those two files should be read.

  ---

  XIS225

  The action code 'xxx' found in 'filename' is not valid.

  While processing the specified RC_*.INI file TC found that one of the action codes specified was not valid. For a list of the valid action codes, please refer to How TC Handles SQL Errors.

  ---

  XIS226

  The On Error string must start with OE and cannot be longer than 32 characters.

  While compiling the script, TC encountered a Define_On_Error_String command in which the On Error String was invalid. As the message indicates, it must start with "OE" and it cannot be longer than 32 characters, including the OE.

  For more information about this command, please see Define_On_Error_String.

  ---

  XIS227

  Bad value (xxx); can't have 2 native codes or 2 SQL strings in same command.

  While compiling the script, TC encountered a Define_On_Error_String command in which two SQLSTATE values were specified or two native code values were specified. Only one of each may be specified in one command or you may specify one SQLSTATE and one native code value - which presumably are compatible with each other.

  For more information about this command, please see Define_On_Error_String.

  ---

  XIS228

  Bad value (xxx); SQL string wrong length or invalid native code.

  While compiling the script, TC encountered a Define_On_Error_String command in which an SQLSTATE string was specified and it was the wrong length or in which TC could not determine if a parameter was an SQLSTATE or a native code value.

  For more information about this command, please see Define_On_Error_String.

  ---

  XIS229

  Must define an SQL state value and/or native code value for xxx

  While compiling the script, TC encountered a Define_On_Error_String command which contained the On Error String name but which did not contain an SQLSTATE value and/or a native code value.

  For more information about this command, please see Define_On_Error_String.

  ---

  XIS230

  Nested Begin_UV statement found; Possible misspelled End_UV

  A second Begin_UV statement was found before the first one was terminated by an End_UV statement.

  ---

  XIS231

  No closing End_UV command found

  The end of the script was found and no closing End_UV was found to match an opening Begin_UV.

  ---

  XIS232

  TC is shutting down due to an apparent database deadlock; examine script and trace.

  TC maintains two ODBC connection handles internally and these handles are apparently deadlocked, probably due to the sequence of steps performed by the script. TC has determined that a deadlock has probably occurred because it has waited for more than the Deadlock_Timeout for a database operation to complete.

  The deadlock timeout defaults to 1 minute but can be changed to up to 60 minutes using the Deadlock_Timeout command. Please see Deadlock_Timeout.

  For information about how to avoid deadlocks caused by the way TC scripts are written, please see ODBC Performance and Deadlocks.

  You should examine your TC script to determine whether this is a normal operation that just took longer than the deadlock timeout. In this case, you should increase the Deadlock_Timeout. If this was not just a case of a normal operation taking longer than the timeout, then you will probably have to add Commit_Changes commands at appropriate places in the script or perhaps redesign the sequence of database operations.

  ---

  XIS233

  Deadlock_Timeout must be in the range of 1 to 60 minutes.

  A Deadlock_Timeout command was found with an invalid value for the number of minutes. Please choose a value from 1 to 60 specifying the number of minutes.

  ---

  XIS234

  Script ended without committing outstanding DB operations; but TC can't force commit because DB is not connected.

  A script has completed without a successful Commit_Changes command being performed after the last PerformInsert, PerformUpdate statement or Begin / End_SQL block (or Begin / End_SQL2, etc). TC would normally force a commit after the script completes but it cannot do so because the database is not currently connected.

  ---

  XIS235

  Illegal attempt to access a subroutine parameter without calling the subroutine.

  TC detected that an attempt was made to use a subroutine parameter when the control of execution entered the subroutine by using a Goto command, a CallSubroutine command or as the result of a branch to an error label for any command that has an error label. In these situations, the subroutine parameters have not been initialized and therefore cannot be used. The only time subroutine parameters can be used is when the subroutine is called using the Call command and the proper number of parameters is specified.

  While TC keeps track of local variables when branching into the middle of a script or subroutine, it is generally not considered proper coding practice to branch into the middle of a script or subroutine.

  ---

  XIS236

  For TRACE_SIZE, the number of files can be 1 to 999 and the size can be 1 to 99 MB.

  The first parameter for the TRACE_SIZE command indicates the maximum number of trace files that TC should maintain for the current session. This can a value from 1 to 999. The second parameter, which is optional, indicates the size that each trace file should be allowed to grow to before TC moves to the next trace file. This size can be a number from 1 to 99 indicating the number of megabytes.

  ---

  XIS237

  Warning: it took xx seconds to write a Send_Term_UV_Data request to the Asynch thread's pipe.

  This diagnostic message indicates TC took a while to queue up a request to write a set of user variables to a certain terminal. This probably means processing of transactions by the current script has been held up for quite a while, even a minute or more. This can occur if a deadlock timeout has occurred (usually about a minute). During the delay a number of transactions could have been queued up. When the delay ends all of these transactions are processed quickly which in turn can quickly fill up the Asynch Set UV thread's queue of requests.

  ---

  XIS238

  Received error error value when attempting to write a Send_Term_UV_Data request to the Asynch thread's pipe.

  An error occurred when the TC script tried to queue up a request to send user variable data to a terminal. The error code should give more information about what the problem is.

  ---

  XIS239

  Detected a change in allocated memory when processing command numeric command value (next one in trace). Change was from xxxxx K to yyyyy K.

  This warning message indicates that TC has detected that its allocated memory has increased during the processing of the specified command. If this occurs repeatedly, this could eventually cause problems in this system as more and more resources are used up.

  This message was originally added when it was found that DB/2 8.1 had a memory leak.

  ---

  XIS240

  Extra UV thread shutting itself down due to 5 minutes of inactivity.

  This informational message is given when one of the extra UV threads shuts itself down. In order to speed up the processing of Asynch set UV requests, TC will start extra threads so that simultaneous processing of requests can be performed. If after a thread has been started, that thread detects that it has not handled any requests in the last 5 minutes, that thread will shut itself down to free up resources for the system.

  There will always be at least one thread handling Asynch requests, even if no requests are issued for more than 5 minutes.

  ---

  XIS241

  Semaphore call operation name in code module failed with return code = operating system error value

  A system error occurred when trying to perform a function with a semaphore. Semaphores are used to synchronize operations between different TC threads. The specified function was attempted from the specified code module. The error value shown is the one returned by the operating system. If this error should occur frequently, notify your IBM support representative.

  ---

  XIS242

  Too many Start_WS / StartInterface scripts defined (up to 125 of each are allowed).

  No more than 125 Start_WS scripts can be defined in a single TC session; nor can more than 125 StartInterface scripts be defined in a single TC session. If more are needed, they must be defined in a separate TC session.

  ---

  XIS243

  Duplicate interface name found: interface name. All interface names must be unique.

  In a given TC session, each StartInterface command must use an interface name different from all other interface names in that script.

  ---

  XIS244

  Not compiling a StartInterface script.

  An EndInterface command was encountered; however a StartInterface script is not currently being compiled. Most likely, a different kind of Endxxxx command is needed instead.

  ---

  XIS245

  The interface name, interface name, referenced at line nn of file file name was not found in any StartInterface command.

  The Interface_Configure command at the specified line references an interface name that is not defined in any StartInterface command anywhere in the script. Check the spelling of the interface name in the specified Interface_Configure command as well as the interface names in all of your StartInterface commands.

  ---

  XIS246

  Failed to open the interface 'interface name'; rc = nn.

  The thread that TC started to open and read requests from the specified interface, received a non-zero return code when attempting to open the interface. Because the implementation of the interface itself is outside of the control of TC, you must check with the creator of the interface to determine what the return code means.

  ---

  XIS247

  The command name command is not allowed unless the current transaction came through a StartInterface script.

  An Interface_Forward_Xact command, Interface_Reply_To_Xact command or XML_Interface_Reply_To_Xact command was encountered; however a StartInterface script is not currently being processed. These commands are intended to handle a transaction that was read from an interface; so they must be within a StartInterface / EndInterface script.

  ---

  XIS248

  The Release_Xact command is only valid for mailbox transactions and interface transactions.

  The Release_Xact is valid only when processing transactions; it is not valid when processing validation requests or data requests.

  ---

  XIS249

  Time format must be either YYMMDDHHmmSS, YYYYMMDDHHmmSS or YYYY?MM?DD?HH?mm?SS. The string provided was data part value.

  The Set_Xact_Time_Of_Origin command accepts only 3 formats for the date and time string. Those valid formats are the ones given in the message above. For more information about this command, see Set_Xact_Time_Of_Origin.

  The message shows the value of the data part used in the Set_Xact_Time_Of_Origin command.

  ---

  XIS250

  Data part data part name is not valid for the current mailbox transaction/validation request/data request/interface transaction.

  The specified data part name is not a valid data part for the kind of input that is currently being processed. For example, TERMSEQ is not valid for a validation request or a data request. For a table of what data parts are valid for each input type, please see Data Parts.

  ---

  XIS251

  The commands Interface_Forward_Xact, Interface_Reply_Xact and XML_Interface_Reply_Xact aren't allowed after the transaction has been released.

  When processing a StartInterface script, once the code has issued the Release_Xact command, none of the three commmands listed above are valid until the next transaction is received for the interface.

  ---

  XIS252

  Failed to release an interface transaction; rc = nn.

  TC received a non-zero return code when attempting to call the release function of the interface that is currently in use. Because the implementation of the interface itself is outside of the control of TC, you must check with the creator of the interface to determine what the return code means.

  ---

  XIS253

  Error reading from interface interface name, rc = nn.

  TC received a non-zero return code when attempting to read the next transaction from specified interface. Because the implementation of the interface itself is outside of the control of TC, you must check with the creator of the interface to determine what the return code means.

  ---

  XIS254

  Additional error text: error text.

  When an error occurs while working with an interface (e.g. reading, forwarding, replying, configuring, ...) TC asks the interface whether there is information in addition to the return code that it can show about that error. Any additional error information returned by the interface is displayed with this message. See the previous message for the specific function that failed, as well as the return code that was received during that failure.

  ---

  XIS255

  Error configuring interface interface name, rc = nn.

  TC received a non-zero return code when attempting to call the configure function for the specified interface. Because the implementation of the interface itself is outside of the control of TC, you must check with the creator of the interface to determine what the return code means.

  ---

  XIS256

  Error forwarding an interface transaction, rc = nn.

  TC received a non-zero return code when attempting to call the forward function of the interface that is currently in use. Because the implementation of the interface itself is outside of the control of TC, you must check with the creator of the interface to determine what the return code means.

  ---

  XIS257

  Error replying to an interface transaction, rc = nn.

  TC received a non-zero return code when attempting to call the reply function of the interface that is currently in use. Because the implementation of the interface itself is outside of the control of TC, you must check with the creator of the interface to determine what the return code means.

  ---

  XIS258

  Process ID for session controller ID is process ID value

  Informational message which gives the numeric value for the process ID that is assigned to this TC session by the operating system. The message also shows the controller ID that is assigned to this session by the script (which will be 'Z' if none is explicitly assigned).

  ---

  XIS259

  Environment variable not defined: %variable%

  When trying to resolve an environment variable found in an Imbed, Open_File_Data, Log_Xact, Submit_Validation, Log_Data, Append_UV_Kbd_Data / Append, or Set_UV_Kbd_Data / Set command, that environment variable was not defined by the operating system. Make sure the spelling of the environment variable is correct. Also make sure the environment variable is defined as expected.

  ---

  XIS260

  Environment variable substitution would be too long for: %variable%

  TC has resolved the specified environment variable but has determined that if it tried to substitute the definition for the variable name, the resulting string would be too long. It therefore cannot do the substitution. Make sure the environment variable definition and the string are correct.

  ---

  XIS261

  Illegal opening brace

  While compiling the script, TC found an opening brace where it is not allowed. Opening braces are only allowed immediately following an If, Else or Do command. Note that the If Check_MW, If Check_Screen, If Check_Color, ... commands can have the opening brace follow them as well.

  ---

  XIS262

  Illegal closing brace

  While compiling the script, TC found a closing brace where it is not allowed. Closing braces may not immediately follow an If, Else or Do command.

  ---

  XIS263

  Message type must be one of: Info, Warning or Error (only the first letter is required)

  The message type specified in the command Write_To_Event_Log was not one of the valid choices.

  ---

  XIS264

  Got error 'nn' when attempting to access the Windows event log using source name: 'xyz'.

  When TC tried to gain access to the Windows event log using the indicated source name, during the execution of the command Write_To_Event_Log, it received the indicated return code value. Consult Windows documentation for the meaning of the return code.

  ---

  XIS265

  Got error 'nn' when attempting to write a message to the Windows event log.

  When TC tried to write to the Windows event log after successfully opening the log during the execution of the command Write_To_Event_Log, it received the indicated return code value. Consult Windows documentation for the meaning of the return code.

  ---

  XIS266

  The SQL buffer size must be at least 4000 bytes, the default value.

  For the command SQL_Buffer_Size, the size specified must be at least 4000 bytes, which is the default value.

  ---

  XIS267

  The running version of the DCConnect Server does not support large/enhanced transactions; TC must use old API.

  This message is given when the version of the DCConnect Server is earlier than October 2004 and therefore does not support large/enhanced transactions and one of two situations is encountered in the TC scripts:

  • A Write_Xact command is encountered that provides a list of mailboxes.

  • A Query_Mailbox command is encountered that is looking for the percent full for the mailbox.

  To resolve the situation, install a version of the DCConnect Server that is later than October 2004.

  ---

  XIS268

  Error closing interface interface name, rc = nn.

  TC received a non-zero return code when attempting to close the specified interface. Because the implementation of the interface itself is outside of the control of TC, you must check with the creator of the interface to determine what the return code means.

  ---

  XIS269

  User variable number xyz is outside the valid range: 1-nnn.

  A reference was made to a user variable number that is outside of the current valid range for user variable numbers.

  By default the valid user variables are UV1 through UV250. However the Define_UVs command may have been used to override the number of user variables. Either correct your script command file or increase the number of user variables by adding/changing the Define_UVs command to your script command file. Then restart the TC session.

  ---

  XIS270

  No more space for StartVal scripts (there are at least nnn defined).

  You can have up to 125 StartVal scripts defined for one TC session.

  If you have more than 125 validation files for which you need to run a script, you need to split your scripts between two or more TC sessions so that the number of validation files handled by each TC session can be reduced.

  ---

  XIS271

  No more space for StartTime scripts (there are at least nnn defined).

  You can have up to 124 StartTime scripts defined for one TC session.

  If you have more than 124 times for which you need to run a script, you need to split your scripts between two or more TC sessions so that the number of time scripts handled by each TC session can be reduced.

  ---

  XIS272

  The specified UV is too small to hold the screen data (RR x CC).

  The specified UV is not big enough to store the entire screen. The screen dimensions are listed in the message.

  If not already doing so, switch to using one of the large user variables.

  ---

  XIS273

  The second parameter must be one of ETS, ALL, CFR, VAL, GRAPHICS or RESET.

  The second parameter of the Load_Term command must be one of the keywords specified in the message above.

  ---

  XIS274

  The third parameter must be one of WHEN_COMPLETE, WHEN_STARTED or WHEN_QUEUED.

  The third parameter of the Load_Term command must be one of the keywords specified in the message above.

  ---

  XIS275

  Write_Xact parameters 9 and beyond cannot be data parts.

  A single data part may be used to specify a mailbox list. That value for that data part can contain more than one name in the list.

  ---

  XIS276

  Can't have literal and data part or two data parts both used for the mailbox list in the Write_Xact command.

  For the Write_Xact command, the mailbox list must be specified either as a single data part that will contain, at runtime, a list of valid mailbox names (separated by one or more spaces or commas) or as a list of literal mailbox names right in the Write_Xact command. You can't have more than one data part for the mailbox list and you can't have both a mailbox list data part and a literal list of mailbox names in the same Write_Xact command.

  Also make sure that any timestamp parameter is of the proper format. If a timestamp parameter is intended to be provided - either literally or as a data part - and TC examines the value for the timestamp and finds it is not in the valid format (YYMMDHHMMSS or YYYYMMDDHHMMSS) then TC will assume it is actually part of the mailbox list.

  ---

  XIS277

  Outgoing raw/XML message truncated to nn characters.

  When executing the XML_Send command for a 'raw' format message, the total length including the "RAWnnnnn" prefix exceeds the maximum message length allowed: 16383 bytes.

  ---

  XIS278

  Incoming raw/XML message truncated to nn characters.

  When executing the XML_Send command for a 'raw' format message, the user variable which has been specified as the target for the message response is not big enough to accommodate that message response.

  If you are using a small user variable for this response, switch to using a large user variable. Large user variables can hold up to 16383 bytes of data; however small user variables can only hold up to 235 bytes of data.

  ---

  XIS279

  End_WS command found without matching Start_WS command.

  An End_WS command was encountered; however a Start_WS script is not currently being compiled. Most likely, a different kind of Endxxxx command is needed instead.

  ---

  XIS280

  The CURRENT_DIR command failed with the error: nn.

  When attempting to execute the CURRENT_DIR command, which is done during the compilation of the script files, the command failed, giving the specified return code.

  Verify that the specified directory exists. If an environment variable was specified, whether as the entire parameter or as part of the string, ensure that that environment variable is defined and has the expected value.

  ---

  XIS281

  Non-referenced label: label name

  After TC compiles the entire script it cross references all specified labels with all branches to those labels. For any label that is found that has no branch to it, this warning message is logged, indicating the label name. This is just a warning; so nothing has to be fixed. But you might want to remove unused labels.

  ---

  XIS282

  Subroutine is not called: subroutine name

  After TC compiles the entire script it cross references all defined subroutines with all calls to those subroutines. For any subroutine that is found that has no call to it, this warning message is logged, indicating the subroutine name. This is just a warning; so nothing has to be fixed. But you might want to remove unused subroutines.

  ---

  XIS283

  System command terminated due to excessive run-time

  The System command had a timeout specified and the specified command did not complete before that timeout expired. Examine the command and its results to determine if that timeout needs to be increased.

  ---

  XIS284

  Database/data source name has not been defined with Database / DB command

  When multiple ODBC connections are in use, therefore requiring that each database-related command include the data source variable at the beginning, TC was unable to resolve that initial variable for the command that had this error.

  Make sure the data source variable is used in all database-related commands. And make sure each references the correct alias.

  ---

  XIS285

  Database/data source must have a unique alias

  When compiling a DB / Database command, TC has detected that the specified command specifies an alias name for the second parameter that has already been used in another DB / Database command.

  Examine all DB / Database commands and make sure each has a unique alias. And of course, make sure all other database-related commands are using the correct aliases.

  ---

  XIS286

  XML handle nn had to be automatically cleaned-up after script ended. Check your code for a missing XML_Cleanup command

  When a script ends, TC checks whether there are any active handles that were allocated via an XML_Create or XML_CreateBOD command or the response to an XML_Send or XML_SendBOD command. These should all be cleaned up in the script using the XML_Cleanup command on each handle. But if this is not done, TC will do the cleanup automatically on the active handles - and log this message as well.

  Using the trace, look for the command that allocated the handle and determine where it should be cleaned up (using the XML_Cleanup command) in the script.

  ---

  XIS287

  Web service function had error creating COM object. Dialog showed error code.

  While trying to perform the specified TC web service function, TC was unable to complete the function because it could not create the .Net COM object needed for web services functions. Prior to the logging of this message, you should have received a popup that gave information about the error that occurred when attempting to create that COM object.

  ---

  XIS288

  XML string had to be truncated to nn characters to fit into the UV; original length was nn.

  The XML_ToString command 'flattened' the specified XML message to a string but that resulting string was too large to fit into the target user variable. If the target user variable was not a large user variable, consider switching to a large user variable. If a large user variable was already being used, the Define_Large_UV_Size command can be used to increase the size of large UVs.

  ---

  XIS289

  The search scope must be one of LDAP_SCOPE_BASE, LDAP_SCOPE_ONELEVEL or LDAP_SCOPE_SUBTREE. It was set to: bad value.

  As the message says, there are only 3 possible values for the search scope value in the LDAP_ChangePassword, LDAP_Search and LDAP_ValidateUser commands.

  ---

  XIS290

  Error detail from previous LDAP call: detailed error message

  Whenever any of the LDAP_xxx commands is not successful and the error was returned from the LDAP interface DLL (TCLDAP.DLL), a detailed error message is retrieved and is logged in this message. Look in the trace log to see the actual TC command to which this error applies.

  ---

  XIS291

  Trace WriteFile error errorCode caused toggle off of tracing

  To prevent the trace errors from interfering with script processing, tracing was turned off after the specified error was encountered.

  ---

  XIS292

  Trace slowness caused toggle off of tracing

  To prevent slowness with writing to trace files from interfering with script processing, tracing was turned off after it was detected that trace logging was slowing down.

  ---

  XIS294

  The Begin_SQL / Begin_UV statement on line lineNumber exceeds the maximum size allowed: maxNumChars

  The SQL statement on the specified line is longer than the specified maximum allowed. This maximum is the size of the internal buffer that is used to hold the statement. The SQL statement must be reduced in size in order for TC to be able to process it.

  ---

  XIS295

  Storage exceeds 64K for local variable names

  While compiling a subroutine the names of all local variables are stored in an internal buffer for other referencing during the compile - such as to ensure the same name is not used more than once. The size of this internal buffer was exceeded. Remove any unused local variables and/or shorten their names.

  ---

  XIS296

  XML logging parameters were loaded successfully from fileName.

  Informational message that is logged whenever the XML_LoadLoggingParameters command is executed or when the menu option Trace -> Reload XML Logging Parameters is run.

  ---

  XIS297

  Loading XML logging parameters resulted in error errorCode from fileName.

  When attempting to load logging parameters from the specified file, the specified error occurred. The attempt to load the parameters may have been initiated from the XML_LoadLoggingParameters command or from the menu option Trace -> Reload XML Logging Parameters.

  ---

  XIS298

  For TRACE_DELAY_LIMIT parm 1, the number of seconds of acceptable delay per sample period can be 0 (disable check) to 60.

  Choose 0 to disable or a number of seconds from 1 to 60 for the first parameter of the Trace_Delay_Limit command.

  ---

  XIS299

  For TRACE_DELAY_LIMIT parm 2, the number of seconds for the sample period can be 10 to 600.

  Choose a number of seconds from 10 to 600 for the second parameter of the Trace_Delay_Limit command.

  ---

  XIS300

  For TRACE_DELAY_LIMIT parm 3, the number of minutes until automatic re-enabling of trace can be 0 (disabled) to 480.

  Choose 0 to disable or a number of minutes from 1 to 480 for the third parameter of the Trace_Delay_Limit command.

  ---

  XIS301

  In End_UV / End_SQL, ':literal' is in the text as a literal in file fileName line ##

  This is a warning that a word in the text of an End_UV or End_SQL / End_SQL2 / End_Select / End_Select2 command starts with a colon but there is no valid TC user variable name after that colon. The warning is given in case a user variable was intended but was misspelled. If left unchanged, then the word ':literal' will be simply treated as part of the text.

  ---

  XIS302

  Restart spawned new TC process: process ID.

  Informational message given when the Restart_TC command is executed. The message shows the process ID for the session that is replacing the one that is being restarted.

  ---

  XIS303

  The running version of the DCConnect Server does not support Write_Xact2 (DcxWriteTransactionEx2).

  During the compilation of the script files, the command Write_Xact2 was found. However, the current version of the DCConnect Server that is installed does not support this command. Version 3.0.9e or later of the DCConnect Server is required. The TC command Write_Xact2 corresponds to the DCConnect Server API DcxWriteTransactionEx2.

  ---

  XIS304

  The first parameter must be one of ABSOLUTE_NO or ABSOLUTE_YES.

  The first parameter of the Shutdown_DCConnect command must be either ABSOLUTE_NO or ABSOLUTE_YES.

  ---

  XIS305

  The first parameter must be one of SET_DATETIME, SYNC_DATETIME, SYNC_TERMINALS.

  The first parameter of the Sync_Date_Time command must be one of the following: SET_DATETIME, SYNC_DATETIME or SYNC_TERMINALS.

  ---

  XIS306

  Restarted session waiting for mailbox / application mailbox or application to be available.

  Informational message given when a TC session uses the Restart_TC command and the newly restarted TC session is waiting for its mailbox or validation / data application to be freed up by the original session.

  ---

  XIS307

  The first parameter must be one of MODEL, FUNCTION_GROUP or TERMINAL.

  The first parameter of the Submit_Client_Files command must be one of the following: MODEL, FUNCTION_GROUP or TERMINAL.

  ---

  XIS308

  The fourth parameter must be one of STAGE_ONLY or STAGE_AND_LOAD.

  The fourth parameter of the Submit_Client_Files command must be one of the following: STAGE_ONLY or STAGE_AND_LOAD.

  ---

  XIS309

  Invalid value name (value name). The second parameter must be a list of TC value names such as STATUS, DESCRIPTION or PROCESS_ID.

  The second parameter of the TC_Get_Session_Values command must be one of the following: ALARM_TIME, COMMAND_LINE, DATABASE, DATABASE_TYPE, DESCRIPTION, EMUL_SHORT_NAME, EMUL_TYPE, LAST_EVENT, MAILBOX, PROCESS_ID, SCRIPT, START_TIME, STATUS or TRACE_ACTIVE.

  ---

  XIS310

  Invalid command (TC command). The second parameter must be a TC command such as SHUTDOWN_WHEN_IDLE or TRACE_ON.

  The second parameter of the TC_Send_Session_Command must be one of the following SHUTDOWN_ABNORMAL, SHUTDOWN_NORMAL, SHUTDOWN_WHEN_IDLE, TRACE_OFF or TRACE_ON.

  ---

  XIS311

  Invalid controller ID: controller ID.

  The controller ID provided as the first parameter of the TC_Get_Session_Values or TC_Send_Session_Command command is not a valid 1 character or 2 character controller ID.

  ---

  XIS312

  TC session for controller controller ID is not running.

  Because the TC session for the specified controller ID in the first parameter of the TC_Send_Session_Command command is not currently running, TC is not able to send any command to that session.

  ---

  XIS313

  The parameter name for WS_SetHTTPParameter must be one of ACCEPT, CONTENT_TYPE, METHOD or RESPONSE_TYPE.

  The second parameter of the WS_SetHTTPParameter command must be one of: ACCEPT, CONTENT_TYPE, METHOD or RESPONSE_TYPE.

  ---

  XIS314

  Error decrypting DB PW: return code.

  While executing the DBEncryptedPW command, the attempt to decrypt the password using the provided encrypted password and encryption key, the decryption process returned the specified return code; it should return the length of the decrypted password. Make sure the encrypted password provided for this command matches the output of the TCENCRYPT utility and that the encryption key provided for this command matches the encryption key used when running the TCENCRYPT utility.

  ---

  Commands Quick Reference

  • Command names are not case-sensitive.
  • Parameters marked with a * can be specified either as a constant value, or as the current value of a user variables (for example, UV_VALUE).
  • Parameters in square brackets are optional.

  Append (synonym for Append_UV_Kbd_Data)

  Append (UV, "String")

  Append (UV, NumericConstant)

  Append (UV, CTRL_CODE)

  Append (UV, %EnvironmentVariable%)

  Append_UV_Cntlr_ID (UV)

  Append_UV_Ctrl_ID (UV)

  Append_UV_Data_Part (UV, DATA_PART, START*, LENGTH*)

  Append_UV_File_Data

  Append_UV_File_Data( uvRC, uvTarget, Length*, uvDelimiter )

  Append_UV_File_Data( uvRC, uvTarget, Length* )

  Append_UV_Host_Data (UV, ROW*, COL*, LENGTH*)

  Append_UV_Kbd_Data

  Append_UV_Kbd_Data (UV, "String")

  Append_UV_Kbd_Data (UV, NumericConstant)

  Append_UV_Kbd_Data (UV, CTRL_CODE)

  Append_UV_Kbd_Data (UV, %EnvironmentVariable%)

  Append_UV_Select_Data

  Append_UV_Select_Data (UV, SELECT_ITEM)

  Append_UV_Select_Data (UV, SELECT_ITEM, ERR_LABEL)

  Append_UV_Select_Data (UV, SELECT_ITEM, ERR_LABEL, FORMAT)

  Append_UV_Select_Data2

  Append_UV_Select_Data2 (DataSourceAlias*, UV, SELECT_ITEM)

  Append_UV_Select_Data2 (DataSourceAlias*, UV, SELECT_ITEM, ERR_LABEL)

  Append_UV_Select_Data2 (DataSourceAlias*, UV, SELECT_ITEM, ERR_LABEL, FORMAT)

  Append_UV_Seq_Num (UV)

  Append_UV_UV (TARGET_UV, SOURCE_UV, START*, LENGTH*)

  Append_UV_Xact_Data (UV, DATA_PART, START*, LENGTH*)

  Application (NAME)

  Begin_Select / Begin_Select2 / Begin_SQL / Begin_SQL2 ()

  Begin_UV ()

  Call subr_name ( parm1, parm2, ..., parmN )

  CallSubroutine (SUB_NAME) // Note: This command is deprecated. Use the Call command instead.

  Call_Subroutine (SUB_NAME) // Note: This command is deprecated. Use the Call command instead.

  Capture_Screen (TARGET_UV )

  Change_Term_State / Change_Terminal_State

  Change_Term_State ( TERMINAL_NAME*, SERVICE_STATE_UV, POLLING_STATE_UV)

  Change_Term_State ( TERMINAL_NAME*, SERVICE_STATE_UV, POLLING_STATE_UV, OPT_ERR_LABEL)

  Check_Busy

  Check_Busy (TIME_LIMIT*, LABEL, CONDITION)

  If Check_Busy (TIME_LIMIT*, CONDITION)

  Check_Color

  Check_Color (COLOR, AREA, ROW*, COL*, TIME_LIMIT*, LABEL, CONDITION)

  If Check_Color (COLOR, AREA, ROW*, COL*, TIME_LIMIT*, CONDITION)

  Check_Cursor

  Check_Cursor (ROW*, COL*, TIME_LIMIT*, LABEL, CONDITION)

  If Check_Cursor (ROW*, COL*, TIME_LIMIT*, CONDITION)

  Check_Highlight

  Check_Highlight (HIGHLIGHT, ROW*, COL*, TIME_LIMIT*, LABEL, CONDITION)

  If Check_Highlight (HIGHLIGHT, ROW*, COL*, TIME_LIMIT*, CONDITION)

  Check_II

  Check_II (TIME_LIMIT*, LABEL, CONDITION)

  If Check_II (TIME_LIMIT*, CONDITION)

  Check_MW

  Check_MW (TIME_LIMIT*, LABEL, CONDITION)

  If Check_MW (TIME_LIMIT*, CONDITION)

  Check_Screen

  Check_Screen ([string or data part],ROW*,COL*,TIME_LIMIT*,LABEL,CONDITION)

  If Check_Screen ([string or data part], ROW*, COL*, TIME_LIMIT*,CONDITION)

  Clear_Mailbox

  Clear_Mailbox ( MAILBOXNAME* )

  Clear_Mailbox ( MAILBOXNAME*, OPT_ERR_LABEL )

  Clear_UV (UV)

  Close_Cursor ()

  Close_Cursor2 ( DataSourceAlias* )

  Close_File_Data ()

  Close_When_Complete ()

  Cntlr (ID)

  //Comment text

  Commit_Changes (ERROR_LABEL)

  Commit_Changes2 (DataSourceAlias*, ERROR_LABEL)

  Communication_Connect()

  Communication_Disconnect()

  Current_Dir

  Current_Dir ("String")

  Current_Dir (%EnvironmentVariable%)

  Cycle_DCC/2_Export ()

  Cycle_Mailbox ()

  Cycle_Session

  Cycle_Session ()

  Cycle_Session ( DOWN | UP )

  Database (NAME)

  DB (NAME)

  DBEncryptedPW

  DBEncryptedPW ( ENCRYPTED_PASSWORD, ENCRYPTION_KEY )

  DBEncryptedPW ( ENCRYPTED_PASSWORD, ENCRYPTION_KEY, DataSourceAlias )

  DBPassword

  DBPassword ( PASSWORD )

  DBPassword ( PASSWORD, DataSourceAlias )

  DBType ( DB2 | ODBC | NONE )

  DBUserid ( USERID )

  DB_Null_Empty ()

  DB_Null_Space ()

  DB_Null_Text ()

  Deadlock_Timeout ( MINUTES )

  Declare ( local_UV_Name )

  Define_Large_UV_Size ( SIZE_IN_BYTES )

  Define_On_Error_String ( String, native code | SQLSTATE, [ SQLSTATE | native code ]  )

  Define_UVs ( TOTAL_NUMBER, NUMBER_OF_LARGE )

  Delay

  Delay (QTY_MILLISECS*)

  Delay (KEY)

  Description (TEXT)

  Do

  Done ()

  Dont_Maintain_Window_Position

  DP_Is_Comma ()

  Dump_UVs ()

  Else

  Emultype ( PCOMM | CM )

  End ()

  EndCluster ()

  EndFunctionGroup ()

  EndInterval ()

  EndKey ()

  EndLogoff ()

  EndLogon ()

  EndMatch ()

  End_Select (ERR_LABEL)

  End_Select2 (Data_Source_Alias*, ERR_LABEL)

  End_SQL (ERR_LABEL)

  End_SQL2 (Data_Source_Alias*, ERR_LABEL)

  EndSub ()

  EndSubroutine ()

  End_TC ()

  EndTime ()

  EndTimeout ()

  End_UV ( TARGET_UV )

  EndVal ()

  End_WS / EndWebService ()

  Export ( NAME | REMOTE_VALIDATION | DATA_REQUEST )

  Format_UV

  Format_UV (UV, field_type)

  // field_type = CHARACTER | NUMERIC | DATE | TIME | TIMESTAMP

  Format_UV (UV, field_type, custom_form)

  // custom_form = CUSTOM_CHARACTER | CUSTOM_NUMERIC

  Format_UV (UV, REAL_NUM, total_length, fractional_length, sign_allowed)

  Format_UV (UV, strip_style, strip_char) // strip_style = STRIP_LEADING_CHARS | STRIP_TRAILING_CHARS | STRIP_ALL_CHARS

  Format_UV(UV, UPPER_CASE)

  Format_UV(UV, LOWER_CASE)

  Format_UV(UV, TAKE_LEADING_CHARS, numToTake*)

  Format_UV(UV, DROP_LEADING_CHARS, numToDrop*)

  Format_UV(UV, TAKE_TRAILING_CHARS, numToTake*)

  Format_UV(UV, DROP_TRAILING_CHARS, numToDrop*)

  Format_UV(UV, PAD_LEADING, padChar, finalLength*)

  Format_UV(UV, PAD_TRAILING, padChar, finalLength*)

  Format_UV(UV, TAKE_MID_CHARS, start*, numToTake*)

  Format_UV(UV, DROP_MID_CHARS, start*, numToDrop*)

  Format_UV(UV, ASCII_TO_EBCDIC)

  Format_UV(UV, EBCDIC_TO_ASCII)

  Forward_Data_Request

  Forward_Data_Request ( APPLICATION_NAME* )

  Forward_Data_Request ( APPLICATION_NAME*, ERROR_LABEL)

  Get_Application_List ( LIST_UV, COUNT_UV )

  Get_Cursor (ROW_UV, COL_UV)

  Get_DBType ( TARGET_UV, DataSourceAlias* )

  Get_DCConnect_Status ( STATUS_UV )

  Get_Job_List ( LIST_UV, COUNT_UV )

  Get_Length (UV, DATA_PART)

  Get_Mailbox_List ( LIST_UV, COUNT_UV )

  Get_Named_Term_UV_Data ( TERM_NAME, UVn, TERMUV* )

  Get_Named_Terminal_UV_Data ( TERM_NAME, UVn, TERMUV* )

  Get_Term_List / Get_Terminal_List

  Get_Term_List( LIST_UV, COUNT_UV )

  Get_Term_List( LIST_UV, COUNT_UV, JOB_NAME* )

  Get_Term_UV_Data ( UV, TERMUV )

  Get_Terminal_UV_Data ( UV, TERMUV )

  Goto label

  If

  If ( DATA_PART_A(START, LENGTH) COMPARE DATA_PART_B(START, LENGTH) )

  If ( "String" | NumericConstant COMPARE DATA_PART_B(START, LENGTH) )

  If ( DATA_PART_A(START, LENGTH) COMPARE "String" | NumericConstant)

  If ( DATA_PART_A COMPARE DATA_PART_B )

  If ( "String" | NumericConstant COMPARE DATA_PART_B )

  If ( DATA_PART_A COMPARE "String" | NumericConstant )

  If ( DATA_PART_A, START, LENGTH, COMPARE, DATA_PART_B, START, LENGTH )

  If ( "String" | NumericConstant, COMPARE, DATA_PART_B, START, LENGTH )

  If ( DATA_PART_A, START, LENGTH, COMPARE, "String" | NumericConstant)

  If (NOT(C1))

  If (! (C1))

  If ((C1) AND (C2))

  If ((C1) && (C2))

  If ((C1) & (C2))

  If ((C1) OR (C2))

  If ((C1) || (C2))

  If ((C1) | (C2))

  If ((C1) AND NOT ((C2) OR (C3 AND C4)))

  Imbed (FILENAME)

  Initiate_Term_Event / Initiate_Terminal_Event

  Initiate_Term_Event ( TERMNAME_UV, EVENT_ID )

  Initiate_Term_Event ( TERMNAME_UV, EVENT_ID, ERR_LABEL )

  Insert_DB_Table (QUALIFIER.TABLE_NAME*)

  Label:

  LDAP_AdminBind ( LDAP_Connection_Handle_UV, LDAP_Server*, Port*, LDAP_Version*, Admin_User_dn*, Admin_Encrypted_PW*, Blowfish_Key*, Error_label )

  LDAP_AdminUnbind ( LDAP_Connection_Handle_UV, Error_label )

  LDAP_ChangePassword ( LDAP_Connection_Handle_UV, Base_dn*, Search_Scope*, UserID_Search_Criteria*, Encrypted_Old_PW*, Encrypted_New_PW*, Blowfish_Key*, PW_Attribute_Name*, Error_label )

  LDAP_Encrypt( UV_For_Encrypted_String, String_To_Encrypt, Blowfish_key )

  LDAP_Search ( LDAP_Connection_Handle_UV, Base_dn*, Search_Scope*, Search_Criteria*, Attribute_List*, Result_XML_Handle_UV, Error_label )

  LDAP_ValidateUser ( LDAP_Connection_Handle_UV, Base_dn*, Search_Scope*, UserID_Search_Criteria*, Encrypted_PW*, Blowfish_Key*, Error_label )

  Load_Term / Load_Terminal

  Load_Term ( TERMNAME_UV, WHICH_FILES, RETURN_WHEN )

  Load_Term ( TERMNAME_UV, WHICH_FILES, RETURN_WHEN , ERR_LABEL )

  Load_UVs ()

  Log_Data // MODE = APPEND | OVERWRITE; returns OK | FAIL

  Log_Data (FILENAME, UV, MODE, RC_UV)

  Log_Data (FILENAME.EXT, UV, MODE, RC_UV)

  Log_Data (FILE_UV, UV, MODE, RC_UV)

  Log_Error // TYPE = up to 5 chars. e.g. INFO, WARN, default = ERROR

  Log_Error ("message")

  Log_Error ("message", TYPE)

  Log_Error (UV)

  Log_Error (UV, TYPE)

  Log_Xact (file_name)

  Mailbox (name | REMOTE_VALIDATION | DATA_REQUEST | NO_DCCONNECT)

  Make_Data_Request

  Make_Data_Request (RECEIVER_NAME, SENDER_NAME, REQUEST_UV, REPLY_UV, TIME_LIMIT*)

  Make_Data_Request (RECEIVER_NAME, SENDER_NAME, REQUEST_UV, REPLY_UV, TIME_LIMIT*, ERROR_LABEL)

  Max_Xact_Wait (TIME)

  Multi_Release_Mode ()

  Name_UV ( uv | NEXT_UV, ALIAS )

  No_Display_Execute

  No_Terminate_From_DCConnect

  On_Error_Goto ( SESSION | WEBSERVICE |native code | SQLSTATE | On Error String, ERROR_LABEL)

  Open_File_Data

  Open_File_Data( uvRC, "filename.ext" )

  Open_File_Data( uvRC, DATAPART, START, LENGTH )

  Parse_UV (uvToBeParsed, DISCARD | uvFirstPart, "delimiter" | CTRL_CODE | uvDelimiter, DISCARD | uvLastPart)

  Password ("password")

  Perform_Fetch ( ERROR_LABEL)

  Perform_Fetch2 ( DataSourceAlias*, ERROR_LABEL)

  Perform_Insert ( ERROR_LABEL)

  Perform_Insert2 ( DataSourceAlias*, ERROR_LABEL)

  Perform_Select (ERROR_LABEL)-

  Perform_Update (ERROR_LABEL)

  Query_Mailbox

  Query_Mailbox (mailbox*, uvForNumToRead [, uvForNumToRel [, uvForActive [, uvForCapacity [, uvForLogFileName]]]]  )

  Query_Mailbox (uvMailboxName, uvForNumToRead [, uvForNumToRel [, uvForActive [, uvForCapacity [, uvForLogFileName]]]]  )

  Query_Mailbox (uvMailboxName, uvForNumToRead [, uvForNumToRel [, uvForActive [, uvForCapacity [, uvForLogFileName [, uvForPercentFull]]]]]  )

  Quit_Subroutines ()

  Reenable_Trace_Via_Restart

  Release_Xact ()

  Reply_To_Data_Request

  Reply_To_Data_Request (UV)

  Reply_To_Data_Request (UV, ERROR_LABEL)

  Report_Term_State / Report_Terminal_State

  Report_Term_State ( TERMINAL_NAME*, SERVICE_STATE_UV, POLLING_STATE_UV, OPERATION_UV, STEP_UV)

  Report_Term_State ( TERMINAL_NAME*, SERVICE_STATE_UV, POLLING_STATE_UV, OPERATION_UV, STEP_UV, OPT_ERR_LABEL)

  Report_Term_Version / Report_Terminal_Version

  Report_Term_Version ( TERMINAL_NAME*, VERSION_UV)

  Report_Term_Version ( TERMINAL_NAME*, VERSION_UV, OPT_ERR_LABEL)

  Resize_Both_Panes

  Resize_Execution_Pane_Only

  Resize_Messages_Pane_Only

  Restart_TC ()

  Return ()

  Rollback_Changes (ERROR_LABEL)

  Rollback_Changes2 (DataSourceAlias*, ERROR_LABEL)

  Run_Without_Connect

  Run_Without_Session

  Save_UVs ()

  Screen_Width (WIDTH)

  Select_Column (COLUMN)

  Select_From_DB_Table (QUALIFIER.TABLE_NAME*)

  Select_Group_By (COLUMN)

  Select_Having

  Select_Having (COLUMN, COL_TYPE, COMPARISON, DATA_PART, START, LENGTH)

  Select_Having (COLUMN, COL_TYPE, COMPARISON, DATA_PART, START, LENGTH, PREFIX)

  Select_Having (COLUMN, COL_TYPE, COMPARISON, DATA_PART, START, LENGTH, PREFIX, SUFFIX)

  Select_Order_By (COLUMN)

  Select_Where

  Select_Where (COLUMN, COL_TYPE, COMPARISON, DATA_PART, START, LENGTH)

  Select_Where (COLUMN, COL_TYPE, COMPARISON, DATA_PART, START, LENGTH, PREFIX)

  Select_Where (COLUMN, COL_TYPE, COMPARISON, DATA_PART, START, LENGTH, PREFIX, SUFFIX)

  Send_Host_Data_Part (DATA_PART, START*, LENGTH*, ROW*, COL*, [ ERROR_LABEL ]  )

  Send_Host_Kbd_Data

  Send_Host_Kbd_Data ("String", [ LOCKED_OR_BUSY_LABEL ]  )

  Send_Host_Kbd_Data (NumericConstant, [ LOCKED_OR_BUSY_LABEL ]  )

  Send_Host_Kbd_Data (CNTL_FUNC_KEY , [ LOCKED_OR_BUSY_LABEL ]  )

  Send_Host_UV_Data (UV, LOCKED_OR_BUSY_LABEL)

  Send_Host_Xact_Data (DATA_PART, START*, LENGTH*, ROW*, COL*, [ ERROR_LABEL ]  )

  Send_Named_Term_UV_Data / Send_Named_Terminal_UV_Data // MODE = SYNCH | ASYNCH

  Send_Named_Term_UV_Data (TERM_NAME, UV, TERMUV*)

  Send_Named_Term_UV_Data (TERM_NAME, UV, TERMUV*, MODE)

  Send_Named_Term_UV_Data (TERM_NAME, UV, TERMUV*, MODE, ERR_LABEL)

  Send_Named_Term_UV_Data (TERM_NAME, UVa, TERMUV1*, UVb, TERMUV2*,..., UVx, TERMUVn)

  Send_Named_Term_UV_Data (TERM_NAME, UVa, TERMUV1*, UVb, TERMUV2*,..., UVx, TERMUVn, MODE)

  Send_Named_Term_UV_Data (TERM_NAME, UVa, TERMUV1*, UVb, TERMUV2*,..., UVx, TERMUVn, MODE, ERR_LABEL)

  Send_Term_Data / Send_Terminal_Data

  Send_Term_Data (FROM_ROW*, FROM_COL*, LENGTH*, TERM_UV*)

  Send_Term_Data (FROM_ROW*, FROM_COL*, LENGTH*, TERM_UV*, MODE)

  Send_Term_Data (FROM_ROW*, FROM_COL*, LENGTH*, TERM_UV*, MODE, ERR_LABEL)

  Send_Term_IResp / Send_Terminal_IResp // RESPONSE = POSITIVE | NEGATIVE, BEEP = BEEP | NO_BEEP, DURATION = TIMED | OPERATOR

  Send_Term_IResp (RESPONSE )

  Send_Term_IResp (RESPONSE, BEEP, DURATION, "Message")

  Send_Term_IResp (RESPONSE, BEEP, DURATION, DATA_PART, START*, LENGTH*)

  Send_Term_UV_Data / Send_Terminal_UV_Data // MODE = SYNCH | ASYNCH (default is ASYNCH)

  Send_Term_UV_Data (UV, TERMUV*)

  Send_Term_UV_Data (UV, TERMUV*, MODE)

  Send_Term_UV_Data (UV, TERMUV*, MODE, ERR_LABEL)

  Send_Term_UV_Data (UVa, TERMUV1*, UVb, TERMUV2*,..., UVx, TERMUVn)

  Send_Term_UV_Data (UVa, TERMUV1*, UVb, TERMUV2*,..., UVx, TERMUVn, MODE)

  Send_Term_UV_Data (UVa, TERMUV1*, UVb, TERMUV2*,..., UVx, TERMUVn, MODE, ERR_LABEL)

  Send_Term_VResp / Send_Terminal_VResp ( PASS | FAIL | UNKNOWN )

  Send_To_Host // CURSOR movement = NONE | START | END

  Send_To_Host (DATA_PART, START*, LENGTH*, ROW*, COL*, CURSOR, [ ERROR_LABEL ]  )

  Send_To_Host ("String", ROW*, COL*, CURSOR, [ ERROR_LABEL ]  )

  Send_To_Host (NumericConstant, ROW*, COL*, CURSOR, [ ERROR_LABEL ]  )

  Send_To_Host (CTRL_FUNC_KEY, [ ERROR_LABEL ]  )

  Session (ID)

  Session_Connect

  Session_Connect()

  Session_Connect(PROFILE_PATH_AND_NAME)

  Set (synonym for Set_UV_Kbd_Data)

  Set (UV, "String")

  Set (UV, NumericConstant)

  Set (UV, CTRL_CODE)

  Set (UV, %EnvironmentVariable%)

  Set_Cursor (ROW*, COL*)

  Set_Emulator_Window ( ACTIVATE | DEACTIVATE | MINIMIZE | MAXIMIZE | RESTORE )

  Set_UV_Cntlr_ID

  Set_UV_Ctrl_ID (UV)

  Set_UV_Data_Part (UV, DATA_PART, START*, LENGTH*)

  Set_UV_File_Data

  Set_UV_File_Data( uvRC, uvTarget, Length*, uvDelimiter )

  Set_UV_File_Data( uvRC, uvTarget, Length* )

  Set_UV_Host_Data (UV, ROW*, COL*, LENGTH*)

  Set_UV_Kbd_Data

  Set_UV_Kbd_Data (UV, "String")

  Set_UV_Kbd_Data (UV, NumericConstant)

  Set_UV_Kbd_Data (UV, CTRL_CODE)

  Set_UV_Kbd_Data (UV, %EnvironmentVariable%)

  Set_UV_Select_Data

  Set_UV_Select_Data (UV, SELECT_ITEM, ERR_LABEL)

  Set_UV_Select_Data (UV, SELECT_ITEM, ERR_LABEL, FORMAT)

  Set_UV_Select_Data2

  Set_UV_Select_Data2 (DataSourceAlias*, UV, SELECT_ITEM, ERR_LABEL)

  Set_UV_Select_Data2 (DataSourceAlias*, UV, SELECT_ITEM, ERR_LABEL, FORMAT)

  Set_UV_Seq_Num (UV)

  Set_UV_UV (TARGET_UV, SOURCE_UV, START*, LENGTH*)

  Set_UV_Xact_Data (UV, DATA_PART, START*, LENGTH*)

  Set_Xact_Time_Of_Origin ( DATAPART, START*, LENGTH* )

  Setup_Insert_Field

  Setup_Insert_Field (COLUMN, COL_TYPE, DATA_PART, START, LENGTH)

  Setup_Insert_Field (COLUMN, COL_TYPE, DATA_PART, START, LENGTH, PREFIX)

  Setup_Insert_Field (COLUMN, COL_TYPE, DATA_PART, START, LENGTH, PREFIX, SUFFIX)

  Setup_Update_Field

  Setup_Update_Field (COLUMN, COL_TYPE, DATA_PART, START, LENGTH)

  Setup_Update_Field (COLUMN, COL_TYPE, DATA_PART, START, LENGTH, PREFIX)

  Setup_Update_Field (COLUMN, COL_TYPE, DATA_PART, START, LENGTH, PREFIX, SUFFIX)

  Show_Thread_Messages

  Shutdown_DCConnect

  Shutdown_DCConnect ( ABSOLUTE_NO | ABSOLUTE_YES )

  Shutdown_DCConnect ( ABSOLUTE_NO | ABSOLUTE_YES, OPT_ERR_LABEL )

  Silent

  SQL_Buffer_Size ( NEWSIZE )

  Start_Application

  Start_Application ( APPLICATION_NAME* )

  Start_Application ( APPLICATION_NAME*, OPT_ERR_LABEL )

  StartCluster / StartFunctionGroup (NAME)

  StartInterval (MILLISECONDS)

  StartKey (EVENT_ID)

  StartLogoff ()

  StartLogon ()

  StartMatch ("string", DATA_PART, START, LENGTH)

  StartSubroutine (SUB_NAME) Note: This is deprecated in favor of Sub.

  StartTime (HH:MM:SS)

  StartTimeout ()

  StartVal (NAME.VAL)

  Start_WS / StartWebService

  Sub subr_name ( parm1, parm2, ..., parmN )

  Submit_Client_Files // TargetType = TERMINAL | MODEL | FUNCTION_GROUP, SubmitMode = STAGE_ONLY | STAGE_AND_LOAD

  Submit_Client_Files ( TargetType, TargetName, ClientFilesListPath, SubmitMode )

  Submit_Client_Files ( TargetType, TargetName, ClientFilesListPath, SubmitMode, ErrorLabel )

  Submit_Validation

  Submit_Validation (d:\path\file.ext, FILENAME.VAL)

  Submit_Validation (d:\path\file.ext, FILENAME.VAL, DONT_LOAD )

  Sync_Date_Time

  Sync_Date_Time ( SET_DATETIME | SYNC_DATETIME, YEAR_UV, MONTH_UV, DAY_UV, HOUR_UV, MINUTE_UV, SECOND_UV )

  Sync_Date_Time ( SET_DATETIME | SYNC_DATETIME, YEAR_UV, MONTH_UV, DAY_UV, HOUR_UV, MINUTE_UV, SECOND_UV, OPT_ERR_LABEL )

  Sync_Date_Time ( SYNC_TERMINALS )

  Sync_Date_Time ( SYNC_TERMINALS, OPT_ERR_LABEL )

  System // returns OK | FAILED

  System (RC_UV, "system command"*)

  System (RC_UV, CMD_UV, START*, LENGTH* )

  TC_Get_Active_Sessions ( uvForListOfControllerIDs )

  TC_Get_Session_Values

  TC_Get_Session_Values ( controllerID*, attributeList*, uvValues, "delimiter" | CTRL_CODE | uvDelimiter )

  TC_Get_Session_Values ( controllerID*, attributeList*, uvValues, "delimiter" | CTRL_CODE | uvDelimiter, errorLabel )

  TC_Send_Session_Command

  TC_Send_Session_Command ( controllerID*, sessionCommand*, uvReturnCode )

  TC_Send_Session_Command ( controllerID*, sessionCommand*, uvReturnCode, errorLabel )

  Title (TEXT)

  Trace / Trace ( ON | OFF )

  Trace_Delay_Limit

  Trace_Size

  Trace_Size ( Num_Trace_Files )

  Trace_Size ( Num_Trace_Files, Trace_File_Size )

  Update_DB_Table (QUALIFIER.TABLE_NAME*)

  Update_Where

  Update_Where (COLUMN, COL_TYPE, COMPARISON, DATA_PART, START, LENGTH)

  Update_Where (COLUMN, COL_TYPE, COMPARISON, DATA_PART, START, LENGTH, PREFIX)

  Update_Where (COLUMN, COL_TYPE, COMPARISON, DATA_PART, START, LENGTH, PREFIX, SUFFIX)

  Use_Adjusted_Xact_Time

  UV_Math // Operators: = (set) + (add) - (subtract) * (multiply) / (real division) \ (integer division) % (modulus)

  UV_Math (TARGET_UV, OPERATOR, CONSTANT, [ FORMAT ]  )

  UV_Math (TARGET_UV, OPERATOR, SOURCE_UV, [ FORMAT ]  )

  Wait_Until_Unlocked (ERROR_LABEL)

  While (Do...While) // (Do...While)

  While ( DATA_PART_A(START, LENGTH) COMPARE DATA_PART_B(START, LENGTH) )

  While ( "String" | NumericConstant COMPARE DATA_PART_B(START, LENGTH) )

  While ( DATA_PART_A(START, LENGTH) COMPARE "String" | NumericConstant )

  While ( DATA_PART_A COMPARE DATA_PART_B )

  While ( "String" | NumericConstant COMPARE DATA_PART_B )

  While ( DATA_PART_A COMPARE "String" | NumericConstant )

  While ( DATA_PART_A, START, LENGTH, COMPARE, DATA_PART_B, START, LENGTH )

  While ( "String" | NumericConstant, COMPARE, DATA_PART_B, START, LENGTH )

  While ( DATA_PART_A, START, LENGTH, COMPARE, "String" | NumericConstant )

  While (NOT(C1))

  While (! (C1))

  While ((C1) AND (C2))

  While ((C1) && (C2))

  While ((C1) & (C2))

  While ((C1) OR (C2))

  While ((C1) || (C2))

  While ((C1) | (C2))

  While ((C1) AND NOT ((C2) OR (C3 AND C4)))

  Workstation_Profile / WS_Profile ( PATH_AND_FILE_NAME )

  Write_To_Event_Log

  Write_To_Event_Log ( APPLICATION_NAME*, TYPE, MESSAGE* )

  Write_To_Event_Log ( APPLICATION_NAME*, TYPE, MESSAGE*, ERROR_LABEL )

  Write_Xact / Write_Xact2x

  Write_Xact( FUNCTIONGROUP*, TERMNAME*, EVENT_ID, DATA_PART, START*, LENGTH* )

  Write_Xact( FUNCTIONGROUP*, TERMNAME*, EVENT_ID, DATA_PART, START*, LENGTH*, TIMESTAMP* )

  Write_Xact( FUNCTIONGROUP*, TERMNAME*, EVENT_ID, DATA_PART, START*, LENGTH*, MAILBOXLIST* | "MAILBOX1", "MAILBOX2", ... )

  Write_Xact( FUNCTIONGROUP*, TERMNAME*, EVENT_ID, DATA_PART, START*, LENGTH*, TIMESTAMP*, MAILBOXLIST* | "MAILBOX1", "MAILBOX2", ...)

  Write_Xact2( FUNCTIONGROUP*, TERMNAME*, EVENT_ID, DATA_PART, START*, LENGTH*, SERIAL_KEY*, PRIORITY* )

  Write_Xact2( FUNCTIONGROUP*, TERMNAME*, EVENT_ID, DATA_PART, START*, LENGTH*, SERIAL_KEY*, PRIORITY*, TIMESTAMP* )

  Write_Xact2( FUNCTIONGROUP*, TERMNAME*, EVENT_ID, DATA_PART, START*, LENGTH*, SERIAL_KEY*, PRIORITY*, MAILBOXLIST* | "MAILBOX1", "MAILBOX2", ... )

  Write_Xact2( FUNCTIONGROUP*, TERMNAME*, EVENT_ID, DATA_PART, START*, LENGTH*, SERIAL_KEY*, PRIORITY*, TIMESTAMP*, MAILBOXLIST* | "MAILBOX1", "MAILBOX2", ...)

  Write_Xact22( FUNCTIONGROUP*, TERMNAME*, EVENT_ID, DATA_PART, START*, LENGTH*, SERIAL_KEY*, SERIAL_KEY_2*, PRIORITY* )

  Plus other variations per Write_Xact2

  Write_Xact23( FUNCTIONGROUP*, TERMNAME*, EVENT_ID, DATA_PART, START*, LENGTH*, SERIAL_KEY*, SERIAL_KEY_2*, SERIAL_KEY_3*, PRIORITY* )

  Plus other variations per Write_Xact2

  WS_AddAttribute ( Handle, attribName*, attribValue*, outReturnCodeUV )

  WS_AddHTTPHeader ( Handle, headerKey*, headerValue* )

  WS_Cleanup / WSCleanup ( WSHandleUV )

  WS_CreateElement / CreateWSElement ( Handle, ElementName*, outReturnCodeUV )

  WS_CreateRequest / CreateWSRequest ( outHandle, WebServiceName, outRC )

  WS_CreateResponse / CreateWSResponse ( RequestHandleUV, ResponseHandleUV )

  WS_DefineNamespace ( uvXMLDocument, URI*, Namespace_Abbreviation* )

  WS_DisplayExecutePopups

  WS_EnterElement / WS_EnterElementXPATH / EnterWSElement

  WS_EnterElement ( Handle, ElementName*, outReturnCodeUV )

  WS_EnterElement ( Handle, ElementName*, Occurrence*, outReturnCodeUV )

  WS_EnterElementXPATH ( Handle, XPATHQuery*, outReturnCodeUV )

  WS_GetAttribute ( Handle, attribName*, outAttribValueUV, outReturnCodeUV )

  WS_GetElement / WS_GetElementXPATH / GetWSElement

  WS_GetElement ( Handle, ElementName*, outElementUV, outReturnCodeUV )

  WS_GetElement ( Handle, ElementName*, Occurrence*, outElementUV, outReturnCodeUV )

  WS_GetElementXPATH ( Handle, XPATHQuery*, outElementUV, outReturnCodeUV )

  WS_GetLastErrorText ( outTextUV )

  WS_LeaveElement / LeaveWSElement ( Handle )

  WS_NamespacePop ( Handle, outReturnCodeUV )

  WS_NamespacePush ( Handle, outReturnCodeUV )

  WS_SendRequest / SendWSRequest

  WS_SendRequest( ReqHandle, TargetURI*, outRCUV, outResponseHandleUV, Timeout* )

  WS_SendRequest( ReqHandle, TargetURI*, outRCUV, outResponseHandleUV, Timeout*, outResponseMsgUV )

  WS_SendResponse / SendWSResponse

  WS_SendResponse( ResponseHandle )

  WS_SendResponse( ResponseHandle, MessageText* )

  WS_SetElement / WS_SetElementXPATH / SetWSElement

  WS_SetElement ( Handle, ElementName*, ElementValue*, outReturnCodeUV )

  WS_SetElement ( Handle, ElementName*, Occurrence*, ElementValue*, outReturnCodeUV )

  WS_SetElementXPATH ( Handle, XPATHQuery*, ElementValue*, outReturnCodeUV )

  WS_SetHTTPBody ( Handle, Body* )

  WS_SetHTTPParameter ( Handle, ParameterName*, ParameterValue* )

  WS_ToFile

  WS_ToFile ( UV_Handle, FILENAME [, RC_UV ] )

  WS_ToFile ( UV_Handle, FILENAME.EXT [, RC_UV ] )

  WS_ToFile ( UV_Handle, FILE_UV [, RC_UV ] )

  WS_ToString ( UV_Handle, UV_Target )

  Xact_Age (LABEL, AGE_SECONDS*)

  XML_AddAttribute (UV, Attribute_name*, Attribute_value*  )

  XML_AddField (UV, Field_name* [ [, Attribute_name*], Attribute_value*], Data* )

  XML_Cleanup (UV)

  XML_Configure (Configuration string*)

  XML_CopyElement ( Target_Handle_UV, Source_Handle_UV, Element_name* [ [, Attribute_name*], Attribute_value*] [, Occurrence*], Error_label )

  XML_Create (UV [, File_name* ] )

  XML_CreateBOD (UV, File_name*)

  XML_CreateElement (UV, Element_name* [ [, Attribute_name*], Attribute_value*]  )

  XML_DefineNamespace (uvXMLDocument, URI*, Namespace_Abbreviation*)

  XML_EnterElement (UV, Element_name* [ [, Attribute_name*], Attribute_value*] [, Occurrence*], Error_label)

  XML_GetField (UVa, Field_name* [ [, Attribute_name*], Attribute_value*], UVb)

  XML_GetField2 (UVa, Field_name* [ [, Attribute_name*], Attribute_value*] [, Occurrence*], UVb, Error_label)

  XML_LeaveElement (UV)

  XML_LoadLoggingParameters (Parameter_File*)

  XML_Parse ( UV, XML_String*, Error_Label )

  XML_RedefineNamespaces (uvXMLDocument)

  XML_Send

  XML_Send (UVa, UVb, Timeout, Error_label)

  XML_Send (RAW, UVa, UVb, Timeout, Error_label)

  XML_SendBOD (UVa, UVb, Timeout, Error_label)

  XML_Sender

  XML_Sender (DLL_name)

  XML_Sender (DLL_name:Function_name)

  XML_SetField (UV, Field_name* [ [, Attribute_name*], Attribute_value*], Data*)

  XML_ToFile

  XML_ToFile ( UV_Handle, FILENAME [, RC_UV ] )

  XML_ToFile ( UV_Handle, FILENAME.EXT [, RC_UV ] )

  XML_ToFile ( UV_Handle, FILE_UV [, RC_UV ] )

  XML_ToString (UV_Handle, UV_Target )

  ---

  Examples

  This appendix contains the following examples:

  • Using Oracle stored procedures
  • Using SQL Server stored procedures
  • Creating a badge file at 4:00 a.m.
  • Verifying a badge against the database.

  ---

  Using Oracle Stored Procedures/Functions

  This stored procedure returns a single results set of two columns (name, userid) from an employee list, selecting where the people are all in a specific work group. This could be expanded to pass in more parameters, but is restricted to having a single result set returned.

  // Stored proc is in a package: 
  // CREATE PACKAGE ODBCRefCur4 AS                                                             
  // TYPE ename_cur IS REF CURSOR;                                                                                                                      
  // PROCEDURE EmpCurs4(Ename IN OUT ename_cur,  workgroup IN VARCHAR2);    
  // END;                                                                                     
  // 
  // CREATE PACKAGE BODY ODBCRefCur4 AS PROCEDURE EmpCurs4(Ename IN OUT ename_cur, workgroup IN VARCHAR2) AS   
  // 
  // BEGIN                                                                                                                           
  // IF NOT Ename%ISOPEN                                                                                                             
  // THEN                                                                                                                            
  // OPEN Ename for SELECT NAME, EMPLOYEE from system.emplgrp WHERE WORK_GROUP = workgroup;                                                                                 
  // END IF;                                                                                                                         
  //                                                                                                                                                                                                                                                     
  // END;   
  // END; 
  
     DBTYPE( ODBC ) 
     DB ( myOraODBCds, ORA )   // Alias is 'ORA' for ODBC DS myOraODBCds 
         
     Set_UV_Kbd_Data( WorkGroup, "SU" )
  
     // Call stored procedure using package and proc names. 
     // Note that only input parms are included -- don't list output cursors in the parms
     // to the procedure.  
     Begin_SQL()
       {Call odbcrefcur4.empcurs4(  :WorkGroup(C)  )}
     End_SQL2( ORA )
     
     Call SQL100()  // Setup vector to a handler that records if 'no record found' condition is hit
                    // Handler will set var gSQLRC ) 
     
     Perform_Fetch2( ORA )
     
     If( gSQLRC == "" )   // If found a row...
     {
       // Keep processing rows until all done
       Do
       {
         Set_UV_Select_Data( vName, 1 )
         Set_UV_Select_Data( vID, 2 )
         ... do some work ... 
         Perform_Fetch2( ORA ) 
       }
        While ( gSQLRC == "" ) 
     }
  
    ...
  
    StartSubroutine ( SQL100 )
  
      Clear_UV( gSQLRC )
      On_Error_Goto( 100, HandleSQL100 )
  
    EndSubroutine ( SQL100 )
  
  
    StartSubroutine ( HandleSQL100 )
  
      Set_UV_Kbd_Data( gSQLRC, "NG" )
      On_Error_Goto( 100, NULL )
      Commit_Changes()
  
    EndSubroutine ( HandleSQL100 )
  
  
  

  Calling a stored procedure (no output result set nor return code):

  
          Begin_SQL ( )
          
             Begin  xxdc_inv_local_trans_handler.submit_trx_to_adapter(:uvtGROUPID(C)); END;
                                         
          End_SQL ( )
  
  

  Calling a function (with output data):

  
        Begin_SQL ( )
              
        SELECT xxdc_local_inv_util.get_inv_org_id(:uvtORGANIZATION(C)) FROM dual
        
        End_SQL ( Account_Error )
        
        Perform_Fetch ( Account_Error )
        Set_UV_Select_Data ( oorg, 1, Account_Error )
  

  Using SQL Server Stored Procedures/Functions

  For SQL Server, the following example illustrates a stored procedure that does a SELECT statement so that TC can access the result set from that SELECT statement.

  In addition, the raiserror statement illustrates how the stored procedure can generate specific SQL errors that can be referenced in an On_Error_Goto statement or in RC_ODBC.INI / RC_USER.INI. It was found that it is necessary to include the statement "SET NOCOUNT ON" at the start of any SQL Server stored procedure that might call raiserror. Without that statement, errors triggered by the raiserror call are not fed back properly to TC through the ODBC layers.

  // 
  // DoMath - This stored procedure takes two numbers and calculates the quotient, product, sum and difference of those
  // two numbers.  But if 0 is passed for the second parameter, a divide by zero error is raised.  The SQLSTATE for this
  // error is 42000 and the SQL native value is 50000 because the text is hard-coded as the first parameter of the 
  // raiserror statement.
  //
  //
  // CREATE PROCEDURE [dbo].[DoMath]
  // @value1       float,
  // @value2       float
  // AS
  //
  // begin
  //
  // SET NOCOUNT ON
  //
  // if @value2 = 0 
  //    raiserror('DoMath: divide by zero error.', 18, 1, null)
  // else
  //    SELECT @value1 / @value2 Quotient, @value1 * @value2 Product, @value1 + @value2 Sum, @value1 - @value2 Difference
  //
  // end
  //
  
          Call SQL100(); // See this TC routine above in the previous section about Oracle stored procedures
  	On_Error_Goto( 50000, DivideByZero )
  
  	Begin_SQL()
  
  		{ Call DoMath( 23, 0) }    
  
  	End_SQL( HandleDoMathFailed )
  
  	Perform_Fetch( HandleFetchFailed ) // grab data from stored procedure
  
  	do
  	{
  	
  		if (uvgSQLRC = "")
  		{
  	        	Set_UV_Select_Data(  Quotient, 1, lblFetchColumnFailed )
  			Log_Error(Quotient)
  			Set_UV_Select_Data(  Product, 2, lblFetchColumnFailed )
  			Log_Error(Product)
  			Set_UV_Select_Data(  Sum, 3, lblFetchColumnFailed )
  			Log_Error(Sum)
  			Set_UV_Select_Data(  Difference, 4, lblFetchColumnFailed )
  			Log_Error(Difference)
  		}
  
  	}
  	while (uvgSQLRC = "")
  
  	Commit_Changes( )
  
  	Goto NextStep
  
  DivideByZero:
          Log_Error("Divide by zero error");
  	Goto NextStep
  
  NextStep:
  
  EndLogon()
  

  Creating a Badge File at 4:00 a.m.

    Silent
    Trace
   
    /////////////////////////////////////////////////////
    // Automatic Creation of Badge File from DB        //
    /////////////////////////////////////////////////////
    StartTime( 04:00:00 )
   
      Name_UV( UV1, uvBadgeNumber )
   
      Clear_UV( uvBadgeNumber )
   
      // Overwrite yesterday's file
      Log_Data( BADGES.DAT, uvBadgeNumber,  OVERWRITE )
  

      // Extract all of the valid badge numbers from
      // the employee database
      Begin_SQL()
   
        SELECT
          BADGE
        FROM EMPLOYEES
   
      End_SQL(SQLerror)
  

      // Copy the badge numbers from the rows of the report
      // into a flat file
    More:
      Perform_Fetch(No_More_Data)
      Clear_UV( uvBadgeNumber )
      Append_UV_Select_Data( uvBadgeNumber, 1, SQLerror )
   
      Append_UV_Kbd_Data( uvBadgeNumber, CRLF )  //Carriage return/line feed
  

      Log_Data( BADGES.DAT, uvBadgeNumber, APPEND )
   
      Goto (More)
   
      // Submit the flat file to DCConnect
    No_More_Data:
      Submit_Validation( C:\CPROGS\XIS\BADGES.DAT, CFG888.VAL )
  

    SQLerror:
   
    EndTime()
  

  ---

  Verifying a Badge against the Database

    Silent
   
    /////////////////////////////////////////////////////
    // Verify Badge is in Database Table               //
    // Direct employee to guard house if DB is down    //
    /////////////////////////////////////////////////////
   
    // This script allowed to run without a DB connection
    Run_Without_Connect
   
    StartVal(BADGES.VAL)
   
      // "Connection does not exist" error results when trying select without DB
      // connection. (In DB2, SQLCODE = -1024, in ODBC, SQLSTATE = 08003).
      On_Error_Goto( OE DB CONNECTION DOES NOT EXIST, DB_IS_DOWN )
   
      Clear_UV(1);
  

      Select_From_DB_Table( EMPLOYEES )
      Select_Column( FIRST_NAME )
      Select_Where( BADGE_NUMBER, CHARACTER, =, TXNDATA, 0, 0)
   
      Perform_Select(SQLerror)
   
      // If database error indicates no records found that
      // match the badge number input, then goto label No_such_badge
      Perform_Fetch(No_such_badge)
   
      // Found the badge, send acknowledgment "Thank you, John"
      Append_UV_Kbd_Data( UV1, "Thank you, ")
      // Get first name -- the 1st column in the report
      Append_UV_Select_Data( UV1, 1, No_such_badge)
  

      Close_Cursor()
   
      Send_Term_UV_Data( UV1, 10 )
      Send_Term_VResp( PASS )
      Goto End_badge
   
    // Will branch to here if no such badge
    No_such_badge:
   
      Append_UV_Kbd_Data(UV1, "Sorry, your badge number is invalid")
      Send_Term_UV_Data( UV1, 10, SYNCH)
      Send_Term_VResp( FAIL )
  

      Goto End_badge
   
    // Will branch to here on general SQL errors
    SQLerror:
   
      Append_UV_Kbd_Data(UV1, "System error #001 -- Call SysOp @ 3-9233")
      Send_Term_UV_Data( UV1, 10, SYNCH)
      Send_Term_VResp( FAIL )
      Goto End_badge
   
    // Will branch to here if database or communication link
    // to the database is down.  Tell the worker to enter through
    // the guard shack this time, and indicate failure of validation
    // to the terminal so the turnstile will not unlock.
    DB_IS_DOWN:
   
      Append_UV_Kbd_Data( UV1, "Due to database problems, please       ")
      Append_UV_Kbd_Data( UV1, "enter at the guard house today. Thanks.")
      Send_Term_UV_Data( UV1, 10 )
      Send_Term_VResp( FAIL )
  

   
    End_badge:
   
    EndVal
  

  ---

  Footnotes:

  (1) Double-clicking on the spot with the double asterisks when VIEWing this document brings up the hypertext link to the related material.

  (2) [A] Identifies the start of a function group block for processing transactions. Only transactions from terminals belonging to the SHOP_FLOOR function group are processed somewhere in this function group block. The key ID (transaction ID) in the transaction further defines where in the block the transaction is processed. This is optional if you do not want to base the transaction processing on the function group.

  (3) [B] Identify which terminal event (for example, function key, code scan, and so forth) is handled by this specific StartKey script (for example, F1... F28, BADGE, CLOCKING, PF1...PF12, SHIFT_PF1...SHIFT_PF12, GP1, DI0...DI7, RES2...RES9, RGN1...RGN40 (touch), ADDL1...ADDL8).

  (4) [C] Indicate which DB table to use. Optionally specify an SQL 'qualifier' with the table name: QUALIFIER.TABLENAME. This parameter can also be a Data part containing the TABLENAME / QUALIFIER.TABLENAME.

  (5) [D] Repeat the Setup_Insert_Field command up to 255 times to set up which fields you want to receive which data. Specify the table column name, its type (NUMERIC, CHARACTER, TIME, DATE, or TIMESTAMP), the source of the data, the starting location in that source, and the length to copy from that source. In this particular command, a new part is specified starting at character 0, continuing for length 10 in the data area of the transaction generated by terminal key F1.

  (6) [E] Set starting quantity for this new part to 0.0, using NULL (no) data from transaction, and adding a prefix to this of literal 0.0.

  (7) [F] Record the timestamp of when the transaction was entered at the terminal (comes from the transaction record); 12 characters at offset TIMESTAMP.

  (8) [G] Perform the database insert, giving an error recovery label for branch upon SQL error.

  (9) [H] Commit the database changes.

  (10) [I] Branch to end.

  (11) [J] Branch to here when SQL error is encountered during Insert. Use commands to log an error, log transaction, send data to terminal, and so forth, as desired. Also can use On_Error_Goto (prior to Perform_Insert) to branch to different recoveries based on the exact SQL error encountered.

  (12) [K] Label for branch when all finished.

  (13) [L] Tell DCConnect to release this transaction.

  (14) [M] End of key F1 script.

  (15) [N] Have more StartKey scripts for the other transactions that can come from your terminals.

  (16) [O] End the function group section. Add more function groups after this one, each able to have new, unique scripts for transaction programs defined in other function groups.

  (17) [A] Identifies the start of a function group block for processing transactions. Only transactions from terminals belonging to the SHOP FLOOR function group are processed somewhere in this function group block. The key ID (transaction ID) in the transaction further define where in the block the transaction is processed. This is optional if you do not want to base the transaction processing on the function group.

  (18) [B] Identify which terminal event (for example, function key, code scan, and so forth) is handled by this specific StartKey script (for example, F1... F28, BADGE, CLOCKING, PF1...PF12, SHIFT_PF1...SHIFT_PF12, GP1, DI0...DI7, RES2...RES9, RGN1...RGN40 (touch), ADDL1...ADDL8).

  (19) [C] Indicate which DB table to use. Optionally specify an SQL 'qualifier' with the table name: QUALIFIER.TABLENAME.

  (20) [D] Repeat the Setup_Update_Field command up to 255 times to set up which fields you want to be updated with which data. Specify the table column name, its type (NUMERIC, CHARACTER, TIME, DATE, or TIMESTAMP), the source of the data, the starting location in that source, and the length to copy from that source.

  In this particular command, we use the optional prefix on the transaction data ("QUANTITY + ") to make the SQL statement add the current value in the QUANTITY column to the data from the transaction. This could also be accomplished by setting the prefix to NULL and the suffix to " + QUANTITY".

  (21) [E] Record the timestamp of when the transaction was entered at the terminal (comes from the transaction record, 12 characters at offset TIMESTAMP).

  (22) [F] Specify the WHERE condition of the Update. Specify the column name to be examined, its type, the relationship (comparison condition) desired (=, >, <, and so forth), and the value to be compared against. In this case, find rows where PART_NUMBER equals the data in the first 10 characters of the terminal transaction data.

  (23) [G] Perform the database update, giving an error recovery label for branch upon SQL error.

  (24) [H] Commit the database changes.

  (25) [I] Branch to end.

  (26) [J] Branch to here when SQL error is encountered during Insert. Use commands to log an error, log transaction, send data to terminal, and so forth, as desired. Also, can use On_Error_Goto (prior to Perform_Insert) to branch to different recoveries based on the exact SQL error encountered.

  (27) [K] Label for branch when all finished.

  (28) [L] Tell DCConnect to release this transaction.

  (29) [M] End of key F2 script.

  (30) [N] Have more StartKey scripts for the transactions that can come from your terminals.

  (31) [O] End the function group section. Add more function groups after this one, each able to have new, unique scripts for transaction programs defined in other function groups.

  (32) [B] Identify which terminal event (for example, function key, code scan, and so forth) is handled by this specific StartKey script (for example, F1... F28, BADGE, CLOCKING, PF1...PF12, SHIFT_PF1...SHIFT_PF12, GP1, DI0...DI7, RES2...RES9, RGN1...RGN40 (touch), ADDL1...ADDL8).

  (33) [C] Indicate which DB table to use. Optionally specify an SQL 'qualifier' with the table name: QUALIFIER.TABLENAME.

  (34) [D] Repeat the Select_Column command up to 255 times to set-up which fields (columns) you want to select from the table. This may include column operations such as the maximum value in a column of a report -- MAX(PART_NUMBER), arithmetic involving time value columns -- STOP_TIME - START_TIME, sum of all values in a column of the report -- SUM(QUANTITY), and so forth, as allowed by SQL.

  (35) [E] Specify the WHERE condition of the select. Specify the column name to be examined, its type, the relationship (comparison condition) desired (=, >, <, and so forth), and the value to be compared against. In this case, find rows where PART_NUMBER equals the data in the first 10 characters of the terminal transaction data.

  (36) [F] Perform the database select, giving an error recovery label for branch upon SQL error.

  (37) [G] Do a Fetch to get the first row of results from the query. Branch to a label if there are no rows in the report or if your cursor is located on the last row already.

  (38) [H] Clear TC user variable number 1. This is NOT to be confused with a data collection terminal user variable. The TC user variables are maintained in the TC session. They retain their values as each transaction is processed (for example, they are never cleared except by a TC script command).

  (39) [I] Append the first column (in this case, the only column) of this row of the results (there should only be one, since PART_NUMBER column has only unique values) to user variable 1.

  (40) [J] Send TC user variable 1 to user variable 10 on the terminal that generated the transaction being processed.

  (41) [K] Branch to end.

  (42) [L] Branch to here when SQL error is encountered during the query. Use commands to log an error, log transaction, send data to terminal, and so forth, as desired. Also can use On_Error_Goto (prior to Perform_Insert) to branch to different recoveries based on the exact SQL error encountered.

  (43) [M] Append data to user variable 1 to tell operator that the part number input was not found in the database.

  (44) [N] Label for branch when all finished.

  (45) [O] Tell DCConnect to release this transaction.

  (46) [P] End of key F3 script.

  (47) [Q] Have more StartKey scripts for the other transactions that can come from your terminals.

  (48) [R] End the function group section. Add more function groups after this one, each able to have new, unique scripts for transaction programs defined in other function groups.

  (49) [B] Identify which terminal event (for example, function key, code scan, and so forth) is handled by this specific StartKey script (for example, F1... F28, BADGE, CLOCKING, PF1...PF12, SHIFT_PF1...SHIFT_PF12, GP1, DI0...DI7, RES2...RES9, RGN1...RGN40 (touch), ADDL1...ADDL8).

  (50) [C] Extract from the terminal transaction record the starting part number field. TC finds variable-length fields that are delimited by semi-colons. TXNFIELD1 is the first field, TXNFIELD2 is the second, and so forth. Then format the user variable for use in the database as a numeric value.

  (51) [D] This command indicates the beginning of a free-form SQL statement. Include any SINGLE valid SQL statement after the Begin_SQL command (or Begin_SQL2 / Begin_Select / Begin_Select2) and prior to the ending End_SQL command (or End_SQL2 / End_Select / End_Select2). Include references to the current value of user variables by using the ':UVn' form (for example, :UV1, :UV12, and so forth). At execution time, the :UVn reference will be replaced inline with the user variables current value.

  (52) [E] If using DB2, refer to the DB2 online SQL Reference manual for information on the various elements of valid SQL statement. If using an ODBC connection to a data source other than a DB2 database, use the documentation that is provided with that database software.

  (53) [F] This signifies the ending of the free-form SQL statement. The SQL statement is now prepared and executed. If any SQL error is encountered, execution of the script branches to the error label.

  (54) [G] The Fetch retrieves the next row of data from the report generated by the SELECT SQL statement. User variable one is used to develop the string, "Part Num: xxxxxxx Quantity: nnnnn". The part number xxxxxxx is the first column of the Fetched data, and quantity nnnnn is the second column. This is dictated by the order given in your SELECT statement listing of columns. Repeat this 2 more times to get the 2nd and 3rd rows, if they exist.

  (55) [H] Execution reaches this point when all three rows are fetched, or the report runs out of data.

  (56) [I] Although EndKey automatically closes the SQL cursor, we have a substantial amount of processing to go before we reach the end, so close the cursor explicitly now. This allows other users to update the current record now rather than later (it removes the row LOCK).

  (57) [J] Send some text to terminal user variable 13 to indicate the report is finished. Release the transaction from DCConnect's mailbox and end this script.

  (58) [A] The session has been started with REMOTE_VALIDATION specified as the mailbox. This puts TC into the mode where it reads only remote validation requests from DCConnect, and routes the processing based on the requested validation file name coming from the remote terminal. Instead of specifying a terminal event (for example, F1, F2, and so forth) in a StartKey command, you specify the validation file name in a StartVal command. The validation file name must be all capitals and must contain the.VAL file extension.

  A single session (instance) of TC can handle processing for up to 121 remote validation files.

  (59) [B] Determine if the badge number sent in for validation is correct by trying to find a record for the badge in the EMPLOYEES table.

  (60) [C] Branch to a label if the fetch shows that no such record was found, indicating an invalid badge.

  (61) [D] The SELECT (query) returned a single column, the worker's first name. Build a user variable with the string "Thank you, <first_name>", extracting the first name from the first column of the query report.

  (62) [E] Send the "Thank you..." user variable to the terminal, and then send the validation response (PASS).

  (63) [F] Branch to here if the query returned no data (no such record).

  (64) [G] Create an error message for the worker, send it to the terminal in SYNCHronous mode (TC blocks until DCConnect has actually sent the data) to make sure the user variable data arrives at the terminal prior to the validation response being sent in the next step.

  (65) [H] Give a FAIL remote validation response.

  (66) TC is set to remote validation or data request mode by specifying the mailbox to be REMOTE_VALIDATION or DATA_REQUEST either on the command line or using the mailbox() function.

  (67) The 7524 DCTs and DCTs running the DCConnect Client allow user variables 10 through 99 to be set. The 7527 DCT allows user variables 10 through 19 to be set. The 7526 always allows user variables 1-3 to be set and, if configured to do so in DCConnect, it can also be enabled to allow user variables 4-999 to be set.

  (68) An interactive transaction is specifically a transaction that comes in with an 'I' prefix on the event identifier, having been originated by a terminal operating under interactive mode rules. A terminal can interact with TC through user variables and transactions without being in this formal interactive mode.

  (69) The 7524 DCT and DCTs running the DCConnect Client allow user variables 10 through 99 to be set. The 7527 DCT allows user variables 10 through 19 to be set. The 7526 always allows user variables 1 through 3 to be set and, if configured to do so in DCConnect, it can also be enabled to allow user variables 4 through 999 to be set.

  (70) A constant is a value specified when you develop your command script file that does not change during execution of TC.

  (71) The current terminal is the terminal that originated the transaction currently being processed. Any commands that send responses or data back to the DCT uses the current terminal as the send-to address.

  (72) TC will always create its various log files in the directory indicated by the environment variable TC2. You may need to change the environment variable TC2 to indicate another drive with more space.