Module SessionService

Macros to manipulate and create sessions.

Since: 2.3

Macro Summary
external

LSAF
%lsaf_deletesession(lsaf_sessionid=);
Deletes a session.
external

LSAF
%lsaf_endsession(lsaf_sessionid=);
Ends a session.
external

LSAF
%lsaf_getmysessions(sas_dsname=work.lsafgetmysessions);
Gets the metadata of the sesions that are defined for the current user. The metadata is ...

Deprecated. Replaced by lsaf_getsessionsbyquery in this release, and will be deprecated in a future release.
external

LSAF
%lsaf_getsessionlistsize(lsaf_sessionid=, lsaf_formatvalue=0);
Returns the list size of a session. The macro variable _lsafSessionListSize_ contains the ...
external

LSAF
%lsaf_getsessionlogsize(lsaf_sessionid=, lsaf_formatvalue=0);
Returns the log size of a session. The macro variable _lsafSessionLogSize_ contains the ...
external

LSAF
%lsaf_getsessions(sas_dsname=work.lsafgetsessions);
Gets the metadata for all sessions. The metadata is stored in a SAS data set. The privilege ...

Deprecated. Replaced by lsaf_getsessionsbyquery in this release, and will be deprecated in a future release.
external

LSAF
%lsaf_getsessionsbyquery(lsaf_userid=, lsaf_engine=, lsaf_type=, lsaf_state=, lsaf_submissionlabel=, lsaf_startedfromdate=, lsaf_startedtodate=, lsaf_endedfromdate=, lsaf_endedtodate=, lsaf_sessionlimit=, sas_dsname=work.lsafgetsessionsbyquery);
Gets the metadata for all of the sessions that are based on a user-specified query. The ...
external

LSAF
%lsaf_getsessionstate(lsaf_sessionid=);
Returns the state of a session. The macro variable _lsafSessionState_ contains the value.
external

LSAF
%lsaf_getusersessions(lsaf_userid=, sas_dsname=work.lsafgetusersessions);
Gets the metadata for all of the user sessions. The metadata is stored in a SAS data set.

Deprecated. Replaced by lsaf_getsessionsbyquery in this release, and will be deprecated in a future release.
external

LSAF
%lsaf_sessionexists(lsaf_sessionid=);
Indicates whether a session exists.

Macro Detail

%lsaf_deletesession(lsaf_sessionid=);

[ Exposure: external ]
Deletes a session.

Syntax:
%LSAF_DELETESESSION(LSAF_SESSIONID=lsaf-sessionid);

          
History:
   2019-10-01
initial code
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
lsaf_sessionid - - Required - The case-sensitive identifier of the session. This can be
        retrieved by calling lsaf_getallsessions, lsaf_getusersessions, or lsaf_getmysessions.
File: lsaf_deletesession.sas
First available in version: 2.3

%lsaf_endsession(lsaf_sessionid=);

[ Exposure: external ]
Ends a session.

Syntax:
%LSAF_ENDSESSION(LSAF_SESSIONID=lsaf-sessionid);

          
History:
   2019-12-02
initial code
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
lsaf_sessionid - - Required - The case-sensitive identifier of the session. This can be
        retrieved by calling lsaf_getallsessions, lsaf_getusersessions, or lsaf_getmysessions.
File: lsaf_endsession.sas
First available in version: 2.3

%lsaf_getmysessions(sas_dsname=work.lsafgetmysessions);

[ Exposure: external ]

Deprecated. Replaced by lsaf_getsessionsbyquery in this release, and will be deprecated in a future release.

Gets the metadata of the sesions that are defined for the current user. The metadata is
stored in a SAS data set.

Syntax:
%LSAF_GETMYSESSIONS(<SAS_DSNAME=SAS-data-set>);

NOTE: This macro will be deprecated in a future release and is replaced by
lsaf_getsessionsbyquery.

          
History:
   2020-02-11
initial coding
   2020-11-23
deprecation message added in header
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
sas_dsname - - Optional - The name of the output SAS data set to contain the metadata
        for the sesions, specified as libref.dataset. The default value is
        WORK.LSAFGETMYSESSIONS. The data set contains a row for each session
        and columns with the following names:
        - sessionId: The unique identifier for the session.
        - dateStarted: The date on which the session started.
        - dateStartedSASFormat: The date on which the session started in SAS DATETIME
        format.
        - dateEnded: The date on which the session ended.
        - dateEndededSASFormat: The date on which the session started in SAS DATETIME
        format.
        - sessionType: The session type.
        - sessionOwner: The session owner.
        - sessionStatus: The session status.
        - submissionLabel: The label of the session, if present.
        - clientId: The client identifier in which the session resides.
File: lsaf_getmysessions.sas
First available in version: 2.3

%lsaf_getsessionlistsize(lsaf_sessionid=, lsaf_formatvalue=0);

[ Exposure: external ]
Returns the list size of a session. The macro variable _lsafSessionListSize_ contains the
value.

Syntax:
%LSAF_GETSESSIONLISTSIZE(LSAF_SESSIONID=lsaf-sessionid, LSAF_FORMATVALUE=lsaf-formatvalue);

          
History:
   2020-01-21
initial coding
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
_lsafSessionListSize_ - The size of the session list.
Parameters:
lsaf_sessionid - - Required - The identifier of the session in the repository. This
        can be retrieved by calling the lsaf_getallsessions, lsaf_getmysessions, or
        lsaf_getusersessions macros.
lsaf_formatvalue - - Optional - Indicates whether to format the value. Non-formatted
        returns the raw numeric value in bytes. Formatted output sets the value to the
        character representation with the appropriate label.
        For example, the non-formatted value 1024 would be 1 KB, if formatted.
        Valid values:
        - 0 (Default): Non-formatted value.
        - 1: Formatted value. *;
File: lsaf_getsessionlistsize.sas
First available in version: 2.3

%lsaf_getsessionlogsize(lsaf_sessionid=, lsaf_formatvalue=0);

[ Exposure: external ]
Returns the log size of a session. The macro variable _lsafSessionLogSize_ contains the
value.

Syntax:
%LSAF_GETSESSIONLOGSIZE(LSAF_SESSIONID =lsaf-sessionid, LSAF_FORMATVALUE=lsaf-formatvalue);

          
History:
   2020-01-21
initial coding
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
_lsafSessionLogSize_ - The size of the session log.
Parameters:
lsaf_sessionid - - Required - The identifier of the session in the repository. This
        can be retrieved by calling the lsaf_getallsessions, lsaf_getmysessions, or
        lsaf_getusersessions macros.
lsaf_formatvalue - - Optional - Indicates whether to format the value. Non-formatted
        returns the raw numeric value in bytes. Formatted output sets the value to the
        character representation with the appropriate label.
        For example, the non-formatted value 1024 would be 1 KB, if formatted.
        Valid values:
        - 0 (Default) Non-formatted value.
        - 1: Formatted value.
File: lsaf_getsessionlogsize.sas
First available in version: 2.3

%lsaf_getsessions(sas_dsname=work.lsafgetsessions);

[ Exposure: external ]

Deprecated. Replaced by lsaf_getsessionsbyquery in this release, and will be deprecated in a future release.

Gets the metadata for all sessions. The metadata is stored in a SAS data set. The privilege
PRIVILEGE_MANAGE_ALL_SESSIONS is required to retrieve information. This privilege is required
if the user is trying to retrieve their sessions. If a user is trying to retrieve their
sessions and does not have the privilege, use the lsaf_getmysessions macro.

Syntax:
%LSAF_GETSESSIONS(<SAS_DSNAME=SAS-data-set>);

NOTE: This macro will be deprecated in a future release and is replaced by
lsaf_getsessionsbyquery.

          
History:
   2020-02-11
initial coding
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
sas_dsname - - Optional - The name of the output SAS data set to contain the metadata
        for all the sessions, specified as libref.dataset. The default value is
        WORK.LSAFGETSESSIONS. The data set contains a row for each session and
        columns with the following names:
        - sessionId: The unique identifier for the session.
        - dateStarted: The date on which the session started.
        - dateStartedSASFormat: The date on which the session started, in SAS DATETIME
        format.
        - dateEnded: The date on which the session ended.
        - dateEndededSASFormat: The date on which the session started, in SAS DATETIME
        format.
        - sessionType: The session type.
        - sessionOwner: The session owner.
        - sessionStatus: The session status.
        - submissionLabel: The label of the session, if present.
        - clientId: The client identifier in which the session resides.
File: lsaf_getsessions.sas
First available in version: 2.3

%lsaf_getsessionsbyquery(lsaf_userid=, lsaf_engine=, lsaf_type=, lsaf_state=, lsaf_submissionlabel=, lsaf_startedfromdate=, lsaf_startedtodate=, lsaf_endedfromdate=, lsaf_endedtodate=, lsaf_sessionlimit=, sas_dsname=work.lsafgetsessionsbyquery);

[ Exposure: external ]
Gets the metadata for all of the sessions that are based on a user-specified query. The
metadata is stored in a SAS data set. The privilege PRIVILEGE_MANAGE_ALL_SESSIONS is required
to retrieve sessions that are not owned by the user who runs the macro.

Syntax:
%LSAF_GETSESSIONSBYQUERY(<LSAF_USERID=lsaf-userid, LSAF_ENGINE=lsaf-engine, LSAF_TYPE=lsaf-type,
LSAF_STATE=lsaf-state, LSAF_SUBMISSIONLABEL=lsaf-submissionlabel,
LSAF_STARTEDFROMDATE=lsaf-startedfromdate, LSAF_STARTEDTODATE=lsaf-startedtodate,
LSAF_ENDEDFROMDATE=lsaf-endedfromdate, LSAF_ENDEDTODATE=lsaf-endedtodate,
LSAF_SESSIONLIMIT=lsaf-sessionlimit, SAS_DSNAME=SAS-data-set>);

          
History:
   2020-11-17
initial coding
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
lsaf_userid - - Optional - The user identifier to return from the search. If a value is
        not specified, all users are returned.
lsaf_engine - - Optional - The session engine to return from the search. If a value is
        not specified, all engines are returned. Valid values:
        - SA: The session uses a SAS engine.
        - R: The session uses an R engine.
        - COMPOSITE: The session of a job that uses both a SAS and an R engine.
lsaf_type - - Optional - The session type to return from the search. If a value is not
        specified, all types are returned. Valid values:
        - INTERACTIVE: Initiated by launching the session editor in the application.
        - TEST_JOB: Initiated by testing a job in the workspace.
        - WORKSPACE_JOB: Initiated by running a job in the workspace.
        - PUBLISHED_JOB: Initiated by running a job in the repository.
        - SYSTEM: Initiated by the system internally to perform a function.
        - UNKNOWN: Unknown.
lsaf_state - - Optional - The session state to return from the search. If a value is not
        specified, all session states are returned. Valid values:
        - IDLE: The session is available for code execution.
        - ACTIVE: The code is currently executing in the session.
        - ENDED: Ended and not available for code execution. Session artifacts exist.
        - ENDING: End session has been called and is in the process of ending.
        - BROKEN: Invalid state. Not available for code execution. Session artifacts might
        still exist.
lsaf_submissionlabel - - Optional - The name that is associated with a submission. If a
        value is not provided, all are returned.
lsaf_startedfromdate - - Optional - The started from date range for sessions within a
        specific time period. Values must be one of the formats below. Date values in
        formats other than the two described below result in an execution failure.
        - SAS datetime20. format (such as 02NOV2013:09:33:22): An offset of zero hours
        from GMT is used.
        - SAS E8601DZ25. format (such as 2013-11-02T09:33:22-04:00).
        If a value is not specified, all dates are returned.
lsaf_startedtodate - - Optional - The started to date range for sessions within a specific
        time period. Values must be one of the formats below. Date values in formats
        other than the two described below result in an execution failure.
        - SAS datetime20. format (such as 02NOV2013:09:33:22): An offset of zero hours
        from GMT is used.
        - SAS E8601DZ25. format (such as 2013-11-02T09:33:22-04:00).
        If a value is not specified, all dates are returned.
lsaf_endedfromdate - - Optional - The ended from date range for sessions within a specific
        time period. Values must be one of the formats below. Date values in formats other
        than the two described below result in an execution failure.
        - SAS datetime20. format (such as 02NOV2013:09:33:22): An offset of zero hours
        from GMT is used.
        - SAS E8601DZ25. format (such as 2013-11-02T09:33:22-04:00).
        If a value is not specified, all dates are returned.
lsaf_endedtodate - - Optional - The ended to date range for sessions within a specific
        time period. Values must be one of the formats below. Date values in formats other
        than the two described below result in an execution failure.
        - SAS datetime20. format (such as 02NOV2013:09:33:22): An offset of zero hours
        from GMT is used.
        - SAS E8601DZ25. format (such as 2013-11-02T09:33:22-04:00).
        If a value is not specified, all dates are returned.
lsaf_sessionlimit - - Optional - The maximum number of sessions to return at one time.
        If a value is not specified, all sessions are returned.
sas_dsname - - Optional - The name of the output SAS data set to contain the metadata
        for all the sessions, specified as libref.dataset. The default value is
        WORK.LSAFGETSESSIONSBYQUERY. The data set contains a row for each session and
        columns with the following names:
        - sessionId: The unique identifier for the session.
        - dateStarted: The date on which the session started.
        - dateStartedSASFormat: The date on which the session started, in SAS DATETIME
        format.
        - dateEnded: The date on which the session ended.
        - dateEndededSASFormat: The date on which the session started, in SAS DATETIME
        format.
        - sessionType: The session type.
        - sessionOwner: The session owner.
        - sessionStatus: The session status.
        - submissionLabel: The label of the session, if specified.
        - clientId: The client identifier in which the session resides.
File: lsaf_getsessionsbyquery.sas
First available in version: 2.4

%lsaf_getsessionstate(lsaf_sessionid=);

[ Exposure: external ]
Returns the state of a session. The macro variable _lsafSessionState_ contains the value.

Syntax:
%LSAF_GETSESSIONSTATE(LSAF_SESSIONID=lsaf-sessionid);

          
History:
   2019-12-02
initial code
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
lsaf_sessionid - - Required - The case-sensitive identifier of the session. This can be
        retrieved by calling lsaf_getallsessions, lsaf_getusersessions, or lsaf_getmysessions.
File: lsaf_getsessionstate.sas
First available in version: 2.3

%lsaf_getusersessions(lsaf_userid=, sas_dsname=work.lsafgetusersessions);

[ Exposure: external ]

Deprecated. Replaced by lsaf_getsessionsbyquery in this release, and will be deprecated in a future release.

Gets the metadata for all of the user sessions. The metadata is stored in a SAS data set.

Syntax:
%LSAF_GETUSERSESSIONS(LSAF_USERID=lsaf-userid <,SAS_DSNAME=SAS-data-set>);

NOTE: This macro will be deprecated in a future release and is replaced by
lsaf_getsessionsbyquery.

          
History:
   2019-11-25
initial coding
   2020-11-23
deprecation message added in header
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
Parameters:
lsaf_userid - - Required - The user identifier of the sessions to retrieve.
sas_dsname - - Optional - The name of the output SAS data set to contain the metadata
        for the user sessions, specified as libref.dataset. The default value is
        WORK.LSAFGETUSERSESSIONS. The data set contains a row for each user session
        and columns with the following names:
        - sessionId: The unique identifier for the session.
        - dateStarted: The date on which the session started.
        - dateStartedSASFormat: The date on which the session started, in SAS DATETIME
        format.
        - dateEnded: The date on which the session ended.
        - dateEndededSASFormat: The date on which the session started, in SAS DATETIME
        format.
        - sessionType: The session type.
        - sessionOwner: The session owner.
        - sessionStatus: The session status.
        - submissionLabel: The label of the session, if present.
        - clientId: The client identifier in which the session resides.
File: lsaf_getusersessions.sas
First available in version: 2.3

%lsaf_sessionexists(lsaf_sessionid=);

[ Exposure: external ]
Indicates whether a session exists.

The SAS macro variable _lsafSessionExists_ is set to a value of 1 when the session
exists, and 0 when it does not. In the event of an incorrect call to the macro that
results in an error, the return value of _lsafSessionExists_ is set to -1.

If the user does not have access to the session, the macro returns False. Access
to sessions is controlled by the global privileges PRIVILEGE_CREATE_SASSESSION and
PRIVILEGE_MANAGE_ALL_SASSESSIONS.

Syntax:
%LSAF_SESSIONEXISTS(LSAF_SESSIONID=lsaf-sessionid);

          
History:
   2019-12-02
initial code
Expected Macro Variables:
_lsafMsg_ - The return message.
_lsafRC_ - The return code.
_lsafSessionExists_ - Indicates whether the session exists.
Parameters:
lsaf_sessionid - - Required - The case-sensitive identifier of the session.
        This can be retrieved by calling lsaf_getallsessions, lsaf_getusersessions, or
        lsaf_getmysessions.
File: lsaf_sessionexists.sas
First available in version: 2.3