SAS/SHARE: Learning to Use

Introduction

If you're a new user of SAS/SHARE, this section provides answers to frequently asked questions (FAQs). A step-by-step example exercise shows the different types of activities that are involved when using SAS/SHARE. Where applicable, operating environment specifics are provided.

Note: The following exercise is an example only and should not be used to set up production applications.

If you have some experience with SAS/SHARE and choose not to perform this exercise or read the FAQs, proceed to Using SAS/SHARE Software.

Setting Up Your Operating Environment

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 also supports other communications access methods, which are described in detail in Communications Access Methods for SAS/CONNECT and SAS/SHARE.

To use the TCP/IP access method, you must verify that a SAS/SHARE server ID has been added to the TCP/IP SERVICES file. To find the location of the SERVICES file for your operating environment, see Communications Access Methods for SAS/CONNECT and SAS/SHARE and the documentation for your TCP/IP software.

If a SAS/SHARE server ID has already been added to the SERVICES file, proceed to the next section, Invoking SAS for Client/Server Sessions (All New Users), and use an existing server ID from the SERVICES file in place of &servername in the remainder of this exercise.
If a SAS/SHARE server ID 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, specify a number that is not already specified in the SERVICES file.
Execute the following statement in the server, the client, and the operator sessions:
```
%let servername=demoserv;
```
If you do not have authority to edit the SERVICES file, ask your server administrator to add demoserv to the SERVICES file. A server administrator ensures that SAS/SHARE servers are identified in the SERVICES file on each operating environment that accesses SAS/SHARE.
The TCP/IP access method allows you to specify syntax that uses two consecutive underscores with a port number, in place of a server ID that has been defined in the client TCP/IP SERVICES file. As an alternative to editing the TCP/IP SERVICES file, execute the following statement in the server, the client, and the operator sessions:
```
%let servername=_ _port-number;
```
for port-number specify a number that is not already used in the TCP/IP SERVICES file. Do not space after the first underscore or the second underscore.

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

Invoking SAS for Client/Server Sessions (All New Users)

You need to invoke three SAS sessions for this example exercise. You can run these SAS sessions by logging on to three different machines or by logging on to the same machine three times.

Operating Environment Information: To invoke a SAS session for two clients and the SAS/SHARE server, use the commands that are specific to your operating environment.

Note: Arrange your SAS sessions so that you can see and use all of them while you are doing this exercise, because you will perform specific tasks in the Program Editor window of the user or server sessions.

In this example, one user logs on to the same machine three times.

USER1 is john(1).
USER2 is john(2).
SERVER is demoserv.

Note: Be sure to issue the SAS statements that are appropriate for the specific SAS session. Each step in this example clearly identifies the session for which the instruction is intended.

Starting a SAS/SHARE Server (All New Users)

Note: Usually, a server administrator starts the server so that it is available when end users and applications developers need to share SAS files. It is recommended that the server be run in non-interactive mode.

z/OS Specifics: For the z/OS operating environment, the server should be run in line mode.

Note: In this example exercise, the data is logged for a UNIX operating environment, and the TCP/IP communications access method is used. If you choose a different method, replace tcp in every occurrence of the COMAMID= option with the appropriate access method value.

In the SERVER session, submit the following statements from the Program Editor window:
```
options comamid=tcp;
libname demo (work);
proc server id=&servername authenticate=optional;
run;
```
The LIBNAME statement associates a SAS library reference (libref) with a SAS library.

The omission of the 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.

PROC SERVER manages concurrent update access to SAS 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 libraries.

The value OPTIONAL for the AUTHENTICATE= option allows users with valid access permission to connect to a server without requiring verification. See Ensuring That User IDs Are Valid. For more information about the AUTHENTICATE= option, see the PROC SERVER statement.

Examine the SERVER Log window, which now contains information similar to this:

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

30Apr2007:15:12:09.095 SAS server DEMOSERV started.

Defining a SAS Library to a Server (All New Users)

When you access a SAS 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, which specifies a name for the 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 from the Program Editor window:
```
options comamid=tcp;
libname demo server=&servername;
```
Note: If you are connecting to a server on a remote operating environment, you must specify the network node name in the SERVER= option as follows:
```
server=network-node-name.&servername
```
See the TCP/IP chapter for your specific operating environment in Communications Access Methods for SAS/CONNECT and SAS/SHARE for more information.

Examine the USER1 Log window, which contains the following information:
```
NOTE: Libref DEMO was successfully assigned as follows:
      Engine:        REMOTE
      Physical Name: /local/u/john
1    options comamid=tcp;
2    libname demo server=&servername;
```
For convenience in this exercise, the libref DEMO is associated with the server library WORK. In SAS, the default name WORK means that the data files that are created are temporary.
Examine the SERVER Log window, which now contains information similar to the following lines about your connection to the server. The messages include the server name, the name of the server library that you specified, and the user identification in the form user-ID(n), where n is the server connection number.
```
30Apr2007:15:16:46.521 User john(1) has connected to server demoserv.
30Apr2007:15:16:52.566 User john(1) has created "DMS Process"(1) 
  under "Kernel"(0).
30Apr2007:15:16:59.079 Server library ('/local/u/john' V9) accessed as 
  DEMO by user john(1).
```

Creating a SAS Data Set (All New Users)

In the USER1 session, submit the following from the Program Editor window:
```
data demo.test;
   do i=1 to 5;
      output;
   end;
run;
```
This DATA step creates a SAS data set that contains five observations and one variable that you will use in the remainder of this example. The Log window displays information about the DATA step and the name of the SAS data set that is opened for output and then closed.

Examine the SERVER Log window again.

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

Locking an Observation (All New Users)

In the USER2 session, submit the following from the Program Editor window:
```
options comamid=tcp;
libname demo server=&servername;
proc fsedit data=demo.test;
run;
```
An FSEDIT window appears in the center of the screen. It shows the value 1 in the first observation.
```
i:     1
```
Examine the USER2 Log window, which contains the following information:
```
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, to which information similar to the following lines was added:

30Apr2007:15:29:39.116 User john(2) has connected to server demoserv.
30Apr2007:15:29:42.483 User john(2) has created "Process"(1) 
  under "Kernel"(0).
30Apr2007:15:29:48.155 Server library ('/local/u/john' V9) accessed as 
  DEMO by user john(2).
30Apr2007:15:29:54.124 User john(2) has created "FSEDIT"(2) 
  under "DMS Process"(1).
30Apr2007:15:29:56.109 DEMO.TEST.DATA(1) opened for input/2 via 
  engine V9 by "FSEDIT"(2) of user john(2).
30Apr2007: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 FSEDIT window in the USER2 session, change the value in the first observation by placing the cursor over the value 1 and typing 5, but do not save it.
The FSEDIT window of USER2 now looks like this:
```
i:    5
```

Accessing a Locked Observation (All New Users)

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

proc fsedit data=demo.test;
run;

PROC FSEDIT also accesses the data set that was created by USER1.

When the FSEDIT window appears, the following message is displayed because the first observation is already locked by the PROC FSEDIT statement in USER2's 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 did not save the change in the previous step.

Releasing a Locked Observation (All New Users)

In the USER2 session, close the FSEDIT window by selecting File

Close from the menu. This action releases the observation that was locked by USER2.

Retrying Access to a Locked Observation (All New Users)

After the FSEDIT window in the USER2 session closes, return to the USER1 FSEDIT session, reread the observation by selecting ViewObservation Number from the menu, and type 1 in the resulting pop-up window. Click OK and the USER1 FSEDIT window now looks like this:
```
i:    5
```
Notice that the observation was updated to reflect USER2's change from 1 to 5.
In the FSEDIT window in the USER1 session, change the value from 5 to 4.
The USER1 FSEDIT window now looks like this:
```
i:    4
```

Stopping the Server (All New Users)

Note: In the real world, servers are usually stopped by server administrators, not by end users.

For this example exercise, if you are an end user, stop the server and close all SAS sessions.

In the USER1 session, close the FSEDIT window by selecting FileClose from the menu.

Also, in the USER1 session, stop the server by submitting the following code from the Program Editor window:

proc operate server=&servername;
stop server;
quit;

Examine the USER1 Log window, which now contains the following information:

16   proc operate server=&servername;
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 in the PROC OPERATE statement:

proc operate server=network_node_name.&servername;

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

For SAS/SHARE end users, you have finished the example exercise. See Frequently Asked Questions (FAQs) about SAS/SHARE .

Identifying the Server (Server Administrators and Applications Developers)

Note: Usually, the OPERATE procedure is used by a server administrator; sometimes an applications developer has responsibilities that include server administration.

The remainder of the steps in this section are mainly here for applications developers and server administrators who are continuing this exercise. In the USER2 session, submit the following from the Program Editor window:

proc operate server=&servername;

PROC OPERATE is an interactive procedure that is terminated by a QUIT statement. A RUN statement is not used or needed with a PROC OPERATE statement.

PROC OPERATE manages the execution of a SAS/SHARE server. You must identify which SAS/SHARE 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 in the PROC OPERATE statement:

proc operate server=network_node_name.&servername;

Examine the USER2 Log window, which contains the following information:

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

Usually, 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 operating environment, you might 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 in an earlier step. See Locking an Observation (All New Users).

Viewing the Server Libraries (Server Administrators and Applications Developers)

PROC OPERATE has several commands. You will use some of the commands in the next steps. All output generated by PROC OPERATE is displayed in the Log window.

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

display library _all_;

The DISPLAY LIBRARY command in the PROC OPERATE step displays information about the libref, status, the number of users, and the library name of all SAS libraries that have been defined to the server.

Examine the USER2 Log window.

*** PROBLEM*** Log window is missing in support.sas.com and in source file.

Viewing Information about Clients (Server Administrators and Applications Developers)

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

display user _all_;

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

Examine the USER2 Log window, which now contains the following information:

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

Disconnecting Clients from the Server (Server Administrators and Applications Developers)

In the USER2 session, submit the following 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 terminates or after the window closes.

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

quiesce user 1;
quiesce user john;

Examining the Server Log (Server Administrators and Applications Developers)

In the USER1 session, because the FSEDIT window is still opened, USER1 can still edit the data set that was created in an earlier step. See Creating a SAS Data Set (All New Users). Close the USER1 FSEDIT window by selecting FileClose from the menu.

Examine the SERVER Log window, which displays information similar to the following:

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

Accessing a Closed Server (Server Administrators and Applications Developers)

In the USER1 session, resubmit the following from the Program Editor window:

proc fsedit data=demo.test;
run;

Examine the USER1 Log window, which contains the following information:

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 messages in the Log window tell you that the attempt by USER1 to communicate with the server is rejected. Because USER1 is stopped, you cannot access the data set.

Stopping the Server (Server Administrators and Applications Developers)

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

stop server;
quit;

The STOP SERVER command in the PROC OPERATE step terminates a server as quickly 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 (Server Administrators and Applications Developers)

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