| Previous | Contents | Index |
The client services for DOS support DECnet, Novell NetWare, and TCP/IP
as transports. The network you use has no effect on how you write the
client program. Specify the transport by linking the appropriate
modules into your client program. See Section 4.8 for more
information.
4.3 Writing Version-Checking Routines
TP Desktop Connector software provides entry points to standard
action routines on the desktop system and in the
gateway to allow applications to check for mismatched versions of
software on the desktop system and DIGITAL ACMS systems.
4.3.1 Version-Checking Processing
The following action routines for version checking are defined in the TP Desktop Connector environment:
You can use ACMSDI_GET_VERSION and acmsdi_check_version for example, to compare the creation date of the desktop client program to the creation date of the DIGITAL ACMS application at run time. This helps catch errors related to mismatch of files on the desktop and the OpenVMS systems. If the desktop files are outdated, desktop users must obtain the correct files on their own. No special utility is provided.
To use the version-checking capability, you must supply complementary versions of the action routines on both the OpenVMS submitter node and the desktop system.
The action routines are customer-written. Figure 4-3 shows the processing that occurs during version checking.
Figure 4-3 Version-Checking Processing
Figure 4-3 shows the following processing steps related to version checking:
Version checking is requested during a sign-in. Specify the
ACMSDI_OPT_CHECK_VERSION option on the acmsdi_sign_in call as the
example in DIGITAL TP Desktop Connector for ACMS Client Services
Reference Manual shows. If version checking is enabled on the
OpenVMS system that runs the gateway, the action routines are called
whenever an ENABLE request is received from the application (see
Section 4.3.1).
4.4 AVERTZ Sample Desktop Client Program for DOS
The AVERTZ sample desktop client program for DOS, called CLIENT.EXE, is written in Microsoft C and Microsoft COBOL. Of the numerous third-party presentation tools available, the sample uses only the forms management capabilities available in Microsoft COBOL. This is largely to ensure that the sample is as easily and widely understood as possible. The generic desktop client program routines for the sample described in Section 4.4.1 are in the C language rather than COBOL, because the TP Desktop Connector arguments are easier to manage in C.
Because portable tools can be used, much of the development work for the sample can be done on an OpenVMS system and ported to the desktop system for compilation, linking, and testing. This enables use of a single development environment for both the desktop client program and DIGITAL ACMS parts of the AVERTZ sample application, including using DECset tools.
Some presentation tools are not portable. For those portions of nonportable code, development must be done on the supporting platforms.
Samples are available from Compaq Services for other presentation
tools. Any native presentation tool callable from COBOL or C that uses
a procedural rather than an event-driven model is usable with TP
Desktop Connector blocking client services.
4.4.1 AVERTZ Components for DOS
The TP Desktop Connector components of the CLIENT.EXE sample desktop client program replace the DECforms forms in the DIGITAL ACMS sample application with routines written in Microsoft COBOL and Microsoft C.
These routines in the desktop client program fall into the following categories:
Figure 4-4 shows the categories of routines and their interaction in the sample desktop client program.
The TP Desktop Connector generic presentation procedures are analogous to the DECforms and TDMS services, for example, FORM$TRANSCEIVE and TSS$REQUEST.
Figure 4-4 TP Desktop Connector Sample Components
The user invokes the main routines in the source file CLIENT.C when starting the sample desktop client program. Figure 4-5 shows the processing flow of the desktop client program routines, including both the generic client routines written in C and the application-specific routines written in COBOL.
Figure 4-5 Processing Flow for DOS Sample Desktop Client Program
A main routine sets up the structures needed for calling TP Desktop Connector software. The routine then calls the generic routines client_init, client_get_task, and client_terminate, each of which in turn invokes an application-specific COBOL program to interact with the user, as follows:
The processing model for the sample TP Desktop Connector application
assumes that the user remains signed-in for extended periods of time.
4.4.3 Reusing the CLIENT.EXE Routines
If the processing model described for the sample desktop client program is similar to the one in your solution, use the C language routines without change for the particular solution you are building. Simply change the LOGIN.CBL, MENU.CBL, and LOGOFF.CBL routines to use the chosen presentation tool and modify the user interface presentation style to suit your users.
To increase the likelihood that you can use some of the sample code with minimal changes, the CLIENT.EXE desktop client program routines are organized into two levels: generic and application-specific. Figure 4-6 shows the relationships among these procedures in handling exchange steps within the AVERTZ sample.
Reserve is the only task implemented in the TP Desktop Connector version of AVERTZ. The AVERTZ sample reserve task uses only TRANSCEIVE statements in its task definition. For this reason, the only generic presentation procedures that are invoked on the desktop are acmsdi_enable, acmsdi_disable, and acmsdi_transceive. (Although the C routines do check application-specific characteristics of the records and record identifications, they are classed as generic.)
Figure 4-6 Sample Presentation Procedures
For the AVERTZ sample, the acmsdi_enable procedure simply returns a success status to the TP Desktop Connector code that invokes it. This sample requires no enable-related work.
The generic acmsdi_transceive presentation procedure in the TRANS.C source file looks at the record identifiers of the incoming message to determine what application-specific presentation procedure to call. The generic presentation procedure checks the validity of the record arguments and calls the appropriate application-specific presentation procedure. The application-specific procedures correspond directly to the exchange steps in the AVERTZ reserve task definition shown in Example 4-4.
| Example 4-4 AVERTZ Reserve Task Exchange Steps |
|---|
REPLACE TASK AVERTZ_CDD_TASK:VR_RESERVE_TASK /LIST
.
.
.
EXCHANGE WORK IS
IF (ctrl_key = "MLTSI") THEN
TRANSCEIVE RECORD list_1, list_2 (1)
SENDING vr_control_wksp, vr_si_trans_array_wksp
RECEIVING vr_sites_wksp,
vr_reservations_wksp,
vr_customers_wksp,
vr_control_wksp
WITH SEND CONTROL vr_sendctrl_wksp;
ELSE
TRANSCEIVE RECORD list_3, list_2 (2)
SENDING vr_control_wksp, vr_sites_wksp
RECEIVING vr_sites_wksp,
vr_reservations_wksp,
vr_customers_wksp,
vr_control_wksp
WITH SEND CONTROL vr_sendctrl_wksp;
END IF;
ACTION
IF (ctrl_key = "QUIT") THEN
EXIT TASK;
END IF;
.
.
.
display_cust_info:
EXCHANGE WORK IS
!+
! Multiple customers found, use array to scroll and select one
!-
IF (ctrl_key = "MLTCU") THEN
TRANSCEIVE RECORD list_5, list_6 (3)
SENDING vr_control_wksp, vr_cu_trans_array_wksp,
vr_rental_classes_wksp, vr_sites_wksp
RECEIVING vr_control_wksp, vr_reservations_wksp,
vr_customers_wksp SHADOW IS vr_customers_shadow_wksp,
vr_trans_wksp SHADOW IS vr_trans_shadow_wksp;
ELSE
!+
! One or no customer found, send unique customer record
!-
TRANSCEIVE RECORD list_7, list_6 (4)
SENDING vr_control_wksp, vr_customers_wksp, vr_trans_wksp,
vr_rental_classes_wksp, vr_sites_wksp
RECEIVING vr_control_wksp, vr_reservations_wksp,
vr_customers_wksp SHADOW IS vr_customers_shadow_wksp,
vr_trans_wksp SHADOW IS vr_trans_shadow_wksp;
END IF;
ACTION
CONTROL FIELD ctrl_key
"QUIT" : EXIT TASK;
"CHNGE": MOVE " " TO ctrl_key;
GOTO STEP determine_site;
END CONTROL;
.
.
.
display_resv_no:
EXCHANGE
!+
! Display reservation # and prompt to see if want to check
! car out now.
!-
TRANSCEIVE RECORD list_8, list_9 (5)
SENDING vr_control_wksp, vr_reservations_wksp
RECEIVING vr_control_wksp,vr_reservations_wksp,
vr_customers_wksp;
ACTION
CONTROL FIELD ctrl_key
"QUIT" : EXIT TASK;
END CONTROL;
.
.
.
END BLOCK WORK;
END DEFINITION;
|
Callouts (1) through (5) indicate the exchange steps in the task definition.
Dividing the presentation procedures into generic and application-specific routines isolates in relatively independent modules the presentation code that is unique to the application. In many cases, you can retain this overall structure for your application, writing new application-specific procedures equivalent to GETSITE.CBL and SELCUST.CBL. Modify TRANS.C, SEND.C, RECV.C, ENABLE.C, DISABLE.C, and REQUEST.C to add each application-specific presentation procedure as an element of the case statement in the generic presentation procedure that calls it. For an application whose task definitions use only TRANSCEIVE in its exchange steps, the only generic procedure you must modify is the acmsdi_transceive procedure in TRANS.C.
See DIGITAL TP Desktop Connector for ACMS Installation Guide
for the names of the AVERTZ source directories and a list of their
contents.
4.5 Writing Procedures Using Blocking TP Desktop Client Services
How you handle the user interface for signing in to the DIGITAL ACMS
system, traversing menus, selecting tasks, and signing out of
DIGITAL ACMS is constrained to some degree by the information you must
include in the acmsdi_sign_in, acmsdi_call_task, and acmsdi_sign_out
services.
For example, the sign-in procedure must provide a valid OpenVMS user
name and password on the acmsdi_sign_in service. To accomplish this,
you can follow the AVERTZ sample application provided with TP Desktop
Connector software.
4.5.1 Calling the Sign-In Service
In the CLIENT sample desktop client program, the mainline presentation code calls another routine, client_init, that actually gets the required information from the user. Alternatively, that presentation code can be included in the main part of the desktop client program.
The desktop client program must call the acmsdi_sign_in service with the correct parameters and must handle any error conditions returned. Example 4-5 shows the call in CLIENT.C to a client_init procedure and to acmsdi_sign_in.
| Example 4-5 Signing In the User |
|---|
main
char username[MAX_USERNAME + 1] = "",
password[MAX_PASSWORD + 1] = "",
node[MAX_NODENAME + 1] = "",
.
.
.
** Get signin information from user
*/
client_init(node, (1)
username,
password);
/*
** Sign into remote ACMS node
*/
status = acmsdi_sign_in(node, (2)
username,
password,
0,
&submitter_id);
/*
** Overwrite password for security
*/
for (i = 0; i < MAX_PASSWORD; i++)
password[i] = EOS;
if (status != ACMSDI_NORMAL)
{
fprintf(stderr,"Error signing user %s into node %s.", username, node);
exit;
}
|
The important points of Example 4-5 are as follows:
Example 4-6 shows the COBOL code in the LOGON.CBL program for obtaining the sign-in information from the application user on the desktop system.
| Example 4-6 Login Program |
|---|
PROCEDURE DIVISION USING
NODE-NAME,
USERNAME,
PASSWORD.
000-MAINLINE.
.
.
.
*
* Display login screen
*
MOVE SPACES TO USERNAME, PASSWORD, NODE-NAME.
DISPLAY COLOR-SCREEN.
DISPLAY LOGIN-PANEL.
*
* Get login information from user
*
MOVE "N" TO VALID-DATA-FLAG.
MOVE SPACES TO ERROR-MSG.
MOVE ZEROES TO CURSOR-POSITION.
PERFORM UNTIL VALID-DATA
MOVE "Y" TO VALID-DATA-FLAG
IF (ERROR-MSG NOT EQUAL SPACES)
THEN
DISPLAY ERROR-MSG AT LINE 25 COLUMN 1 WITH BELL
MOVE SPACES TO ERROR-MSG
ELSE
DISPLAY ERROR-MSG AT LINE 25 COLUMN 1
END-IF
ACCEPT LOGIN-PANEL
MOVE ZEROES TO CURSOR-POSITION
IF (USERNAME EQUAL SPACES)
THEN
MOVE "N" TO VALID-DATA-FLAG
MOVE "Username is required" TO ERROR-MSG
MOVE 9 TO CURSOR-LINE
MOVE 35 TO CURSOR-COLUMN
ELSE
IF (PASSWORD EQUAL SPACES)
THEN
MOVE "N" TO VALID-DATA-FLAG
MOVE "Password is required" TO ERROR-MSG
MOVE 10 TO CURSOR-LINE
MOVE 35 TO CURSOR-COLUMN
ELSE
IF (NODE-NAME EQUAL SPACES)
THEN
MOVE "N" TO VALID-DATA-FLAG
MOVE "Login node is required" TO ERROR-MSG
MOVE 12 TO CURSOR-LINE
MOVE 35 TO CURSOR-COLUMN
END-IF
END-PERFORM.
|
The program in Example 4-6 uses the Microsoft COBOL presentation capabilities. You can use other presentation tools that allow developing a more sophisticated user interface.
Some data validation is performed in the login program shown in
Example 4-6. The presentation procedure can ensure the validity of
the data before sending it to TP Desktop Connector Gateway for ACMS
software. Because less invalid data is communicated, the network
traffic between the desktop system and the DIGITAL ACMS system is
minimized.
4.5.2 Enabling Password Expiration Checking
Password expiration checking allows the client application to determine if the end-user's password is expiring soon on the gateway node. If password expiration checking is enabled on both the gateway and on the client's call to the acmsdi_sign_in service, TP Desktop Connector client services indicate how many hours are left until the user's password expires on the gateway node.
To use the password expiration checking option:
long hours_until_password_expiration; ACMSDI_OPTION options[2]; |
options[0].option = ACMSDI_OPT_PWD_EXPIRING; options[0].pwd_expiring_hrs.address = &hours_until_password_expiration; options[1].option = ACMSDI_OPT_END_LIST; |
if (status == ACMSDI_PWDEXPRING)
{
printf("Warning ! Your Password Will Be Expiring in %d Hours!",
hours_until_password_expiration);
}
|
| Previous | Next | Contents | Index |