SAS/SHARE User's Guide

A Getting Started Exercise

Setting Up Your System

The SAS sessions that you use in this exercise exchange data by using a communications access method. For this exercise, the TCP/IP communications access method is used for all operating environments. SAS/SHARE software also supports other communications access methods. These access methods are described in detail in Communications Access Methods for SAS/CONNECT and SAS/SHARE Software.

To use the TCP/IP access method, you must make sure that a SAS/SHARE serverid has been added to the TCP/IP SERVICES file. Refer to the documentation for your TCP/IP software and Communications Access Methods for SAS/CONNECT and SAS/SHARE Software to determine the location of the SERVICES file for your operating environment.

If a SAS/SHARE serverid has already been added to the SERVICES file, skip to the next section Invoking SAS Software for Client and Server Sessions, and use an existing serverid from the SERVICES file in place of demoserv in the rest of this exercise.
If a SAS/SHARE serverid has not already been added to the SERVICES file, edit the SERVICES file and add a line similar to the following:
```
demoserv port-number/tcp  # SAS/SHARE server
```
For port-number, supply a number that is not already used in the SERVICES file.
If you do not have authority to edit the SERVICES file, ask your server administrator to add demoserv to the SERVICES file for you. A server administrator makes sure that SAS/SHARE servers are identified in the SERVICES file on each system from which SAS/SHARE software is accessed.

Note: If you choose to use a communications access method that is different from TCP/IP, some configuration of your operating environment may be required. For more information, see Communications Access Methods for SAS/CONNECT and SAS/SHARE Software. [cautionend]

Invoking SAS Software for Client and Server Sessions

You need to invoke three SAS sessions for this exercise. You can run these SAS sessions by logging on to three different machines or by logging on to the same machine three times. To invoke a SAS session for two clients and the SAS/SHARE server, use the commands that are specific to your operating environment. For OS/390 and CMS, the server should be run in line mode. Arrange your SAS sessions so that you can see and use all of them while you are doing this exercise.

Note: Throughout this exercise you are instructed to perform specific tasks in the Program Editor window of the user or server sessions. To illustrate the example here, one user logs on to the same machine three times. The following conventions are used in this exercise:

USER1 is john(1)

USER2 is john(2)

SERVER is demoserv.

Be sure to issue the SAS statements that are appropriate for the particular SAS session. Each step clearly identifies the session for which the instruction is intended. [cautionend]

Starting a SAS/SHARE Server

Note: As mentioned earlier, this exercise uses the TCP/IP communications access method. If you use a different access method, substitute the appropriate value for the COMAMID= option wherever you see "tcp". [cautionend]

Note: This exercise shows logged data for a UNIX host. [cautionend]

In the SERVER session, submit the following lines from the Program Editor window:
```
options comamid=tcp;
libname demo(work);
proc server id=demoserv authenticate=optional;
run;
```
The omission of either the Version 7 TCPSEC= option or the Version 8 USER= and PASSWORD= options in the LIBNAME statement means that the SAS/SHARE client/server session is running unsecured. The COMAMID= option specifies the access method that is used to communicate between a client SAS session and the server. You must specify the COMAMID= option before you invoke PROC SERVER.
A LIBNAME statement associates a SAS library reference (libref) with a SAS data library.
PROC SERVER manages concurrent update access to SAS data libraries and the members in those libraries. PROC SERVER runs in its own SAS session, which serves client SAS sessions by executing input and output requests to SAS data libraries. The value OPTIONAL for the AUTHENTICATE= option allows trusted users to connect to a server without requiring authentication. See Ensuring That Userids Are Authentic and The SERVER Procedure for more information about the AUTHENTICATE= option to the PROC SERVER statement.

Examine the SERVER Log window:

NOTE: Libref DEMO was successfully assigned as follows:
      Engine:        V8
      Physical Name: /local/u/john
1    options comamid=tcp;
2    libname demo(work);
3    proc server id=demoserv authenticate=optional;
4    run;

21JAN1999:15:12:09.095 SAS server DEMOSERV started.

Typically, a server administrator starts the server or takes steps to have it started so that it is available when the end users and applications developers need to share SAS files. It is recommended that the server be run in non-interactive mode.

Defining a SAS Data Library to a Server

A LIBNAME statement associates a SAS library reference (libref) with a SAS data library. When you access a SAS data library through a server, your SAS session reads from and writes to that data library through the server instead of reading and writing directly to the library.

The first LIBNAME statement that specifies a particular server connects your SAS session to that server. For a client session, you must specify the COMAMID= option before you try to connect to the server.

In the USER1 session, submit the following lines from the Program Editor window:
```
options comamid=tcp;
libname demo server=demoserv;
```
Note: If you are connecting to a server on a remote host, you must specify the network node name in the SERVER= option in the form:
```
server=network-node-name.demoserv
```
See the TCP/IP chapter for your particular operating environment in Communications Access Methods for SAS/CONNECT and SAS/SHARE Software for more information.
Examine the USER1 Log window:
```
NOTE: Libref DEMO was successfully assigned as follows:
      Engine:        REMOTE
      Physical Name: /local/u/john
1    options comamid=tcp;
2    libname demo server=demoserv;
```
For convenience in this exercise, the libref DEMO is associated with the server library WORK. This means that the data files that are created in the exercise are temporary.
Examine the SERVER Log window:
```
21JAN1999:15:16:46.521 User john(1) has connected to server demoserv.
21JAN1999:15:16:52.566 User john(1) has created "DMS Process"(1) 
  under "Kernel"(0).
21JAN1999:15:16:59.079 Server library ('/local/u/john' V8) accessed as 
  DEMO by user john(1).
```
The log displays messages about your connection to the server. The messages include the server name, the name of the server library that you assigned, and the user identification. The user identification has the form userid(n), where n is the server connection number.

Creating a SAS Data Set

In the USER1 session, submit the following lines from the Program Editor window:
```
data demo.test;
   do i=1 to 5;
      output;
   end;
run;
```
This creates a SAS data set that contains 5 observations and 1 variable that you will use in the remaining steps.

Examine the SERVER Log window:

21JAN1999:15:23:17.110 User john(1) has created "DATASTEP"(2) 
  under "DMS Process"(1).
21JAN1999:15:23:20.719 DEMO.TEST.DATA(1) opened  for output via 
  engine V8 by "DATASTEP"(2) of user john(1).
21JAN1999:15:23:26.835 DEMO.TEST.DATA(1) closed by "DATASTEP"(2) 
  of user john(1).
21JAN1999:15:23:27.194 User john(1) has terminated "DATASTEP"(2)
  (under "DMS Process"(1)).

The log displays information about the DATA step and the name of the SAS data set that is opened for output and then closed.

Locking an Observation

In the USER2 session, submit the following lines from the Program Editor window:

options comamid=tcp;
libname demo server=demoserv;
proc fsedit data=demo.test;
run;

An FSEDIT window appears and contains the following information centered on the screen:

i:     1

It shows the value 1 in the first observation.

Examine the USER2 Log window:

NOTE: Libref DEMO was successfully assigned as follows:
      Engine:        REMOTE
      Physical Name: /local/u/sasvcl
1    options comamid=tcp;
2    libname demo server=shr9;
3    proc fsedit data=demo.test;
4    run;

Examine the SERVER Log window:

21JAN1999:15:29:39.116 User john(2) has connected to server demoserv.
21JAN1999:15:29:42.483 User john(2) has created "Process"(1) 
  under "Kernel"(0).
21JAN1999:15:29:48.155 Server library ('/local/u/john' V8) accessed as 
  DEMO by user john(2).
21JAN1999:15:29:54.124 User john(2) has created "FSEDIT"(2) 
  under "DMS Process"(1).
21JAN1999:15:29:56.109 DEMO.TEST.DATA(1) opened for input/2 via 
  engine V8 by "FSEDIT"(2) of user john(2).
21JAN1999:15:29:56.933 DEMO.TEST.DATA(1) reopened for update/R by 
  "FSEDIT"(2) of user john(2).

The FSEDIT procedure accesses the data set that was created by USER1 in the previous section. The first observation is currently locked by USER2 for update access.

In the USER2 FSEDIT window, change the value in the first observation by positioning the cursor over the value 1 and overwriting it with 5, but do not save it.
The FSEDIT window now appears like this:
```
i:    5
```

Attempting to Modify the Locked Observation

In the USER1 session, submit the following lines from the Program Editor window:

proc fsedit data=demo.test;
run;

This procedure also accesses the data set that was created by USER1.

When the FSEDIT window opens, the following message is displayed because the first observation is already locked by USER2's FSEDIT session:

WARNING: User john(2) (server connection 2) is using this observation.

USER1 cannot update the observation until after USER2 releases it. Notice that the value of i is still 1 because USER2 had not saved the change in the previous step.

Releasing the Observation

In the USER2 session, close the FSEDIT window by selecting File -> Close from the pull-down menu. This action releases the observation that was locked by USER2.

Retrying Access to the Observation

After the FSEDIT window in the USER2 session is closed, in the USER1 FSEDIT session, re-read the observation by selecting View -> Observation Number from the pull-down menu and then enter 1 in the pop-up and click OK.
The USER1 FSEDIT window now looks like this:
```
i:    5
```
Notice that the observation was updated to reflect USER2's change to 5.
In the USER1 FSEDIT window, change the value from 5 to 4.
The USER1 FSEDIT window now looks like this:
```
i:    4
```

Stopping the Server

Note: If you are an applications developer or a server administrator, skip to the next section. Identifying the Server. [cautionend]

If you are an end user, you can stop the server and close all SAS sessions in this section. (See Note: immediately following this paragraph.) After you complete the steps in this section, proceed to Frequently Asked Questions.

Note: Servers are typically stopped by server administrators, not by end users. [cautionend]

In the USER1 session, close the FSEDIT window by selecting File -> Close from the pull-down menu.

In the USER1 session, stop the server by submitting the following lines from the Program Editor window:

proc operate server=demoserv;
stop server;
quit;

Examine the USER1 Log window:

16   proc operate server=demoserv;
PROC OPERATE is set to default server DEMOSERV.
==================================================
17   stop server;
Default server DEMOSERV is now stopped.
PROC OPERATE was previously set to default server 
DEMOSERV but is not set to any server now.
==================================================
18   quit;

Note: If you are not on the same machine as the server, you must specify the network node name in the SERVER= option:

server=network_node_name.demoserv

In the SERVER Program Editor window, close the server session by entering the following line:
```
endsas;
```
On both the USER1 and USER2 command lines in the Program Editor window, close the user session by submitting the following command:
```
bye
```

For SAS/SHARE end users, you have finished the exercise.

Identifying the Server

For applications developers and server administrators to continue with this exercise, in the USER2 session, submit the following line from the Program Editor window:

proc operate server=demoserv;

A RUN statement is not used or needed with this statement.

The OPERATE procedure manages the execution of a SAS/SHARE server. You must identify which SAS server you want to manage, even if there is only one server executing. If you are not on the same machine as the server, you must specify the network node name in the SERVER= option:

server=network_node_name.demoserv

PROC OPERATE is an interactive procedure and is terminated by a QUIT statement. PROC OPERATE has several commands. You will use a few of them in the next steps. All output generated by PROC OPERATE is displayed in the Log window.

Examine the USER2 Log window:

proc operate server=demoserv;
PROC OPERATE is set to default server DEMOSERV.

In general, you should specify the COMAMID= option before using PROC OPERATE to connect to a server. If you know that you will use the default access method on your host, you may omit the COMAMID= option. You do not need to specify a value for the COMAMID= option in this step because it was already specified for this SAS session as shown in Locking an Observation.

Note: PROC OPERATE is usually used by a server administrator; sometimes an applications developer has responsibilities that include server administration. [cautionend]

Viewing the Server Libraries

In the USER2 session, submit the following line from the Program Editor window:

display library _all_;

Examine the USER2 Log window. The DISPLAY LIBRARY command displays information about the libref, status, the number of users, and the library name of all SAS data libraries that have been defined to the server.

Viewing Information about Clients

In the USER2 session, submit the following line from the Program Editor window:

display user _all_;

Examine the USER2 Log window.

USER                  NUMBER OF
ID        STATUS      LIBRARIES
-------------------------------
john     ACTIVE         0 
john     ACTIVE         1 
john     ACTIVE         1 
============================== 
7    display user _all_;

The DISPLAY USER command displays information about the userid, the status, and the number of libraries that have been defined by each connected client.

Disconnecting Clients from the Server

In the USER2 session, submit the following line from the Program Editor window:

quiesce user 1 2;

The QUIESCE USER command gradually terminates a user's access to a server by denying new user requests for resources and moving the user from active status to stopped status. The user can continue the SAS program step or window that is currently in use but will not be able to use the server after that step or window terminates.

Users can be identified by userids or connection numbers. For example, user JOHN(1) can be quiesced by either of the following statements:

quiesce user 1;
quiesce user john;

Examining the Server Log

In the USER1 session, because the FSEDIT window is still displayed, USER1 could still edit the data set that was created in Creating a SAS Data Set.
Close the USER1 FSEDIT window by selecting File -> Close from the pull-down menu.

Examine the SERVER Log window, which displays information about disconnecting the quiesced users from the server.

21JAN1999:15:56:57.207 PROC OPERATE command from user john(3): 
  QUIESCE USER 1 2;
21JAN1999:15:59:52.065 DEMO.TEST.DATA(1) closed by "FSEDIT"(3) 
  of user john(1).
21JAN1999:15:00:02.161 User john(1) has terminated "FSEDIT"(3) 
  (under "DMS Process"(1)).

Retrying Access to the Server

In the USER1 session, re-submit the following lines from the Program Editor window:

proc fsedit data=demo.test;
run;

Examine the USER1 Log window:

10   proc fsedit data=demo.test;
You cannot open data set DEMO.TEST.DATA because user JOHN(1) 
is quiesced on server DEMOSERV.
11   run;

NOTE: The SAS System stopped processing this step because of errors.

The log displays information indicating that the attempt to communicate with the server was rejected. Because USER1 is stopped, you are not able to communicate with the server to access the data set.

Stopping the Server

In the USER2 session, submit the following lines from the Program Editor window:

stop server;
quit;

The STOP SERVER command terminates a server as rapidly as possible. If users are connected to the server when you execute a STOP SERVER command, changes that they have not saved are lost. The QUIT command terminates PROC OPERATE in interactive mode.

Closing the SAS Sessions

In the SERVER Program Editor window, close the server session by submitting the following line:
```
endsas;
```
On both the USER1 and USER2 command lines of the Program Editor window, close the user session by submitting the following command:
```
bye
```

Chapter Contents
Previous
Next
Top of Page