The information in this appendix applies only to OpenVMS operating systems.

Your application can use the OpenVMS DECwTermPort routine to create a DECterm window on any node, local or remote. You can also create DECterm windows by spawning a CREATE/TERMINAL command; however, using the DECwTermPort routine provides better performance. (Users can create a DECterm window from the session manager's Applications menu or by using the CREATE/TERMINAL command in DCL.)

Example A-1 illustrates how to use the DECwTermPort routine to create a DECterm window on a remote system.

Example A-1 Creating a DECterm Window on a Remote Node

#include descrip /* descriptor definitions */ #include ssdef /* system status codes */ #include prcdef /* stsflg bits for creating process */ main( ) { int status, stsflg; short device_length; (1)char device_name[50]; $DESCRIPTOR( command, "SYS$SYSTEM:LOGINOUT.EXE" ); $DESCRIPTOR( input_file, "" ); $DESCRIPTOR( output_file, "" ); /* send the message to the controller */ (2)status = DECwTermPort( 0, 0, 0, device_name, &device_length ); if ( status != SS$_NORMAL ) printf( "DECterm creation failed, status is %x\n", status ); else { /* create a process that is already logged in */ /* input from TWn: */ (3)input_file.dsc$w_length = device_length; input_file.dsc$a_pointer = device_name; /* output to TWn: */ output_file.dsc$w_length = device_length; output_file.dsc$a_pointer = device_name; /* make it detached, interactive, logged in */ stsflg = PRC$M_DETACH | PRC$M_INTER | PRC$M_NOPASSWORD; /* create the process */ (4)status = sys$creprc( 0, &command, &input_file, &output_file, 0, 0, 0, 0, 4, 0, 0, stsflg ); if ( status != SS$_NORMAL ) printf( "Could not run LOGINOUT.EXE, status is %x\n", status ); } }

1. The DECwTermPort routine returns the name of the virtual terminal device in this character array.
2. This call to the DECwTermPort routine creates a DECterm window on a remote node. In the example, the display argument is specified as 0. This indicates that the default display should be used. By specifying the second argument as 0, the example uses the default setup file. By specifying the third argument as 0, the example specifies that the default values in the setup and resource files should not be overridden.
   The DECwTermPort routine returns the name of the virtual terminal device in the fourth argument, device_name. The DECwTermPort routine writes the length of the virtual terminal device name in the last argument, device_length.
3. After successfully creating a remote DECterm, the example creates a process that is already logged in.
4. This call to SYS$CREPRC creates the process that runs in the DECterm window. The SYS$INPUT of the process is the DECterm window, and the process is created with a priority of 4. The process is logged in as a detached process.

Example A-2 provides a command procedure to compile, link, and run the example program.

Example A-2 Command Procedure to Compile, Link, and Run a DECterm on a Remote Node

(1)$ cc create_decterm (2)$ link create_decterm, sys$input/opt sys$share:decw$xlibshr/share sys$share:decw$dwtlibshr/share sys$share:vaxcrtl/share sys$share:decw$terminalshr/share (3)$ set display/create/node=mynode (4)$ run create_decterm

1. The command procedure invokes the compiler to compile the example program.
2. The command procedure invokes the linker, specifying the name of the object module and an options file as command line arguments. The options file lists the shareable libraries needed to run the example program. The DECterm shareable image is named decw$terminalshr.
3. The default display is set to point to mynode. Because the display argument to the DECwTermPort routine in Example A-1 was specified as 0 (zero), the DECterm is created on mynode. The same effect could have been achieved by specifying the display argument to the DECwTermPort routine as mynode::0.
4. The command procedure runs the example program.