How to Send Reflection Commands from the Host

  • 7021476
  • 30-Mar-2000
  • 10-Aug-2018

Environment

Reflection 2014
Reflection X 2014
Reflection Pro 2014
Reflection for UNIX and OpenVMS 2014
Reflection for UNIX and OpenVMS 2011
Reflection for UNIX and OpenVMS version 14.x
Reflection Standard Suite 2011
Reflection for HP version 14.x
Reflection for ReGIS Graphics version 14.x

Situation

Reflection can execute Reflection Basic (RB) or Reflection Command Language (RCL) commands sent from a host program. This technical note includes general information, special considerations, and troubleshooting tips for writing host programs that send commands to Reflection.

Resolution

Host-Initiated Programs

Host programs are written in a programming language native to the host, such as DCL, C, or COBOL. Embedded within the host program are Reflection commands written in either RB or RCL. When Reflection receives a command from the host, it will execute that command as though the user had executed it from the command line, the RB script editor, or RCL command window.

Creating a host program requires knowledge of both the host programming language and Reflection scripting languages. For information on RB or the RCL, refer to your Reflection documentation. For information on which programming languages are supported by your host, consult your host documentation.

Note: You cannot send commands to Reflection from a host program using Visual Basic for Applications (VBA); however, you can use the RunMacro or RunExternalMacro methods in a Reflection Basic Script to invoke a VBA macro.

Sending Commands to Reflection

You can send commands to Reflection using either RCL or RB. RCL is recommended for simple commands that do not require OLE (object linking and embedding) technology. For more complex procedures or to use OLE, use RB instead.

General Structure

Commands sent from a host program to Reflection generally go through the same set of steps:

  1. The host program sends an RB script or RCL command to a copy of Reflection.
  2. Reflection evaluates and executes the command sent by the host program.
  3. Reflection optionally returns a completion code to the host program.
  4. The host program accepts the completion code, and then proceeds.

Syntax of Reflection Commands

Regardless of which Reflection scripting language you use, Reflection commands must be contained in a specific escape sequence that tells the host to pass the command to Reflection, rather than executing it on the host. The specific syntax for RB commands is described in KB 7021479. The syntax used to send RCL commands is described in KB 7021478.

Completion Codes

How completion codes are specified depends on whether the host program sends commands to Reflection using RB or RCL. For this reason, completion codes are described in KB 7021479 for RB commands, and KB 7021478 for RCL commands.

Special Considerations

When writing a host program to send commands to Reflection, bear in mind the following special considerations.

HP Emulation: Block Mode vs. Character Mode

When sending commands to Reflection in HP emulation, use HP Character Mode, rather than HP Block Mode.

File Transfers

Many host programs involve a file transfer to or from Reflection at some point. Special considerations that apply to host-initiated file transfers are covered in KB 7021480.

Sample Files

KB 7021639 explains how to obtain sample scripts, settings files, and macros for Reflection 13.0 – 14.x. The samples described in the note demonstrate Reflection product functionality.

You can use the sample files as a starting point in creating your own host programs, however, modifying the files requires knowledge of both the host programming language and Reflection’s scripting languages. Consult your host documentation for information about writing programs for your host computer. For information about Reflection’s scripting languages, refer to your Reflection documentation.

The table below lists two additional examples written by Attachmate technical support engineers. These files are available from download.attachmate.com.

Sample File
Description
RBLaunchIE.udc.txt
This HP 3000 UDC script demonstrates using Reflection Basic to control Internet Explorer.
XferUNIX.txt
This korn shell script demonstrates using RCL to download a file to the pc.

Troubleshooting Tips

If you experience problems running your host program, try the following:

  • Execute Reflection commands manually using the Reflection Basic Editor or RCL command line. If necessary, step through your RB script in the Reflection Basic Editor. For instructions, consult online help in the Reflection Basic Editor.
  • Verify that Reflection is available to execute commands sent by the host program. If Reflection is already executing a script or command file, it will not be able to respond to commands from the host.
  • Generate an event trace, following the instructions in KB 7021622. If you need to call Attachmate technical support, be sure to have your event trace ready.

If you cannot resolve your problem using this technical note, contact Attachmate technical support, https://support.microfocus.com/contact/.

Additional Information

For more programming resources, see KB 7022686.

Legacy KB ID

This document was originally published as Attachmate Technical Note 1223.