sasjs/core
1
0
Fork 0
mirror of https://github.com/sasjs/core.git synced 2025-12-11 06:24:35 +00:00
Code Issues Projects Releases Wiki Activity

chore: docs

Browse Source
This commit is contained in:
Allan Bowe
2021-09-03 10:54:21 +03:00
parent 507557b2cb
commit d93032e1a9
3 changed files with 32 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

34
all.sas
View File

@@ -1642,12 +1642,11 @@ Usage:
recognise this and fetch the log of the parent session instead) recognise this and fetch the log of the parent session instead)
@li STP environments must finish cleanly to avoid the log being sent to @li STP environments must finish cleanly to avoid the log being sent to
_webout. To assist with this, we also run stpsrvset('program error', 0) _webout. To assist with this, we also run stpsrvset('program error', 0)
and set SYSCC=0. For 9.4m3 we take a unique approach - we open a macro and set SYSCC=0. We take a unique "soft abort" approach - we open a macro
but don't close it! This provides a graceful abort, EXCEPT when called but don't close it! This works everywhere EXCEPT inside a \%include inside
called within a %include within a macro (and that macro contains additional a macro. For that, we recommend you use mp_include.sas to perform the
logic). See mp_abort.test.nofix.sas for the example case. include, and then call \%mp_abort(mode=INCLUDE) from the source program (ie,
If you know of another way to gracefully abort a 9.4m3 STP session, we'd OUTSIDE of the top-parent macro).
love to hear about it!
@param mac= to contain the name of the calling macro @param mac= to contain the name of the calling macro
@@ -1657,15 +1656,16 @@ Usage:
within a %include called within a macro. Furthermore, there is no way to within a %include called within a macro. Furthermore, there is no way to
test if a macro is called within a %include. To handle this particular test if a macro is called within a %include. To handle this particular
scenario, the %include should be switched for the mp_include.sas macro. scenario, the %include should be switched for the mp_include.sas macro.
This provides an indicator that we are running a macro within a %include This provides an indicator that we are running a macro within a \%include
(_SYSINCLUDEFILEDEVICE) and allows us to provide a dataset with the abort (`_SYSINCLUDEFILEDEVICE`) and allows us to provide a dataset with the abort
values (msg, mac). values (msg, mac).
We can then run an abort cancel FILE to stop the include running, and pass We can then run an abort cancel FILE to stop the include running, and pass
the dataset back to the calling program to run a regular %mp_abort(). the dataset back to the calling program to run a regular \%mp_abort().
The dataset will contain the following fields: The dataset will contain the following fields:
@li iftrue (1=1) @li iftrue (1=1)
@li msg (the message) @li msg (the message)
@li mac (the mac param) @li mac (the mac param)
@param mode= (REGULAR) If mode=INCLUDE then the &errds dataset is checked for @param mode= (REGULAR) If mode=INCLUDE then the &errds dataset is checked for
an abort status. an abort status.
Valid values: Valid values:
@@ -5445,9 +5445,9 @@ create table &outds (rename=(
%end; %end;
%mend mp_hashdataset;/** %mend mp_hashdataset;/**
@file @file
@brief Performs a %include @brief Performs a wrapped \%include
@details This macro wrapper is necessary if you need your included code to @details This macro wrapper is necessary if you need your included code to
know that it is being %included. know that it is being \%included.
If you are using %include in a regular program, you could make use of the If you are using %include in a regular program, you could make use of the
following macro variables: following macro variables:
@@ -5491,16 +5491,14 @@ https://documentation.sas.com/doc/en/pgmsascdc/9.4_3.5/mcrolref/n1j5tcc0n2xczyn1
@param [in] errds= (work.mp_abort_errds) There is no clean way to end a @param [in] errds= (work.mp_abort_errds) There is no clean way to end a
process within a %include called within a macro. Furthermore, there is no process within a %include called within a macro. Furthermore, there is no
way to test if a macro is called within a %include. To handle this way to test if a macro is called within a %include. To handle this
particular scenario, the %mp_abort() macro ill test for the existence of particular scenario, the %mp_abort() macro will test for the existence of
the _SYSINCLUDEFILEDEVICE variable and return the outputs (msg,mac) inside the `_SYSINCLUDEFILEDEVICE` variable and return the outputs (msg,mac) inside
this dataset. this dataset.
It will then run an abort cancel FILE to stop the include running, and pass It will then run an abort cancel FILE to stop the include running, and pass
the dataset back. the dataset back.
NOTE - it is NOT possible to read this dataset as part of this macro - when NOTE - it is NOT possible to read this dataset as part of _this_ macro -
running abort cancel FILE, ALL macros are closed, so instead it is necessary when running abort cancel FILE, ALL macros are closed, so instead it is
to run the following line in the source program, immediately after any macro necessary to invoke "%mp_abort(mode=INCLUDE)" OUTSIDE of any macro wrappers.
that contains (or contains a macro that contains) this mp_include macro:
</br><code>%mp_abort(mode=INCLUDE)</code>
@version 9.4 @version 9.4

18
base/mp_abort.sas
View File

@@ -15,12 +15,11 @@
recognise this and fetch the log of the parent session instead) recognise this and fetch the log of the parent session instead)
@li STP environments must finish cleanly to avoid the log being sent to @li STP environments must finish cleanly to avoid the log being sent to
_webout. To assist with this, we also run stpsrvset('program error', 0) _webout. To assist with this, we also run stpsrvset('program error', 0)
and set SYSCC=0. For 9.4m3 we take a unique approach - we open a macro and set SYSCC=0. We take a unique "soft abort" approach - we open a macro
but don't close it! This provides a graceful abort, EXCEPT when called but don't close it! This works everywhere EXCEPT inside a \%include inside
called within a %include within a macro (and that macro contains additional a macro. For that, we recommend you use mp_include.sas to perform the
logic). See mp_abort.test.nofix.sas for the example case. include, and then call \%mp_abort(mode=INCLUDE) from the source program (ie,
If you know of another way to gracefully abort a 9.4m3 STP session, we'd OUTSIDE of the top-parent macro).
love to hear about it!
@param mac= to contain the name of the calling macro @param mac= to contain the name of the calling macro
@@ -30,15 +29,16 @@
within a %include called within a macro. Furthermore, there is no way to within a %include called within a macro. Furthermore, there is no way to
test if a macro is called within a %include. To handle this particular test if a macro is called within a %include. To handle this particular
scenario, the %include should be switched for the mp_include.sas macro. scenario, the %include should be switched for the mp_include.sas macro.
This provides an indicator that we are running a macro within a %include This provides an indicator that we are running a macro within a \%include
(_SYSINCLUDEFILEDEVICE) and allows us to provide a dataset with the abort (`_SYSINCLUDEFILEDEVICE`) and allows us to provide a dataset with the abort
values (msg, mac). values (msg, mac).
We can then run an abort cancel FILE to stop the include running, and pass We can then run an abort cancel FILE to stop the include running, and pass
the dataset back to the calling program to run a regular %mp_abort(). the dataset back to the calling program to run a regular \%mp_abort().
The dataset will contain the following fields: The dataset will contain the following fields:
@li iftrue (1=1) @li iftrue (1=1)
@li msg (the message) @li msg (the message)
@li mac (the mac param) @li mac (the mac param)
@param mode= (REGULAR) If mode=INCLUDE then the &errds dataset is checked for @param mode= (REGULAR) If mode=INCLUDE then the &errds dataset is checked for
an abort status. an abort status.
Valid values: Valid values:

16
base/mp_include.sas
View File

@@ -1,8 +1,8 @@
/** /**
@file @file
@brief Performs a %include @brief Performs a wrapped \%include
@details This macro wrapper is necessary if you need your included code to @details This macro wrapper is necessary if you need your included code to
know that it is being %included. know that it is being \%included.
If you are using %include in a regular program, you could make use of the If you are using %include in a regular program, you could make use of the
following macro variables: following macro variables:
@@ -46,16 +46,14 @@ https://documentation.sas.com/doc/en/pgmsascdc/9.4_3.5/mcrolref/n1j5tcc0n2xczyn1
@param [in] errds= (work.mp_abort_errds) There is no clean way to end a @param [in] errds= (work.mp_abort_errds) There is no clean way to end a
process within a %include called within a macro. Furthermore, there is no process within a %include called within a macro. Furthermore, there is no
way to test if a macro is called within a %include. To handle this way to test if a macro is called within a %include. To handle this
particular scenario, the %mp_abort() macro ill test for the existence of particular scenario, the %mp_abort() macro will test for the existence of
the _SYSINCLUDEFILEDEVICE variable and return the outputs (msg,mac) inside the `_SYSINCLUDEFILEDEVICE` variable and return the outputs (msg,mac) inside
this dataset. this dataset.
It will then run an abort cancel FILE to stop the include running, and pass It will then run an abort cancel FILE to stop the include running, and pass
the dataset back. the dataset back.
NOTE - it is NOT possible to read this dataset as part of this macro - when NOTE - it is NOT possible to read this dataset as part of _this_ macro -
running abort cancel FILE, ALL macros are closed, so instead it is necessary when running abort cancel FILE, ALL macros are closed, so instead it is
to run the following line in the source program, immediately after any macro necessary to invoke "%mp_abort(mode=INCLUDE)" OUTSIDE of any macro wrappers.
that contains (or contains a macro that contains) this mp_include macro:
</br><code>%mp_abort(mode=INCLUDE)</code>
@version 9.4 @version 9.4