@sasjs/utils 2.48.2 → 2.49.1

package/macros/mf_getapploc.sas

@@ -0,0 +1,78 @@
+/**
+  @file
+  @brief Returns the appLoc from the _program variable
+  @details When working with SASjs apps, web services / tests / jobs are always
+  deployed to a root (app) location in the SAS logical folder tree.
+
+  When building apps for use in other environments, you do not necessarily know
+  where the backend services will be deployed.  Therefore a function like this
+  is handy in order to dynamically figure out the appLoc, and enable other
+  services to be connected by a relative reference.
+
+  SASjs apps always have the same immediate substructure (one or more of the
+  following):
+
+  @li /data
+  @li /jobs
+  @li /services
+  @li /tests
+  @li /tests/jobs
+  @li /tests/services
+  @li /tests/macros
+
+  This function works by testing for the existence of any of the above in the
+  automatic _program variable, and returning the part to the left of it.
+
+  Usage:
+
+      %put %mf_getapploc(&_program)
+
+      %put %mf_getapploc(/some/location/services/admin/myservice);
+      %put %mf_getapploc(/some/location/jobs/extract/somejob/);
+      %put %mf_getapploc(/some/location/tests/jobs/somejob/);
+
+
+  @author Allan Bowe
+**/
+
+%macro mf_getapploc(pgm);
+%if "&pgm"="" %then %do;
+  %if %symexist(_program) %then %let pgm=&_program;
+  %else %do;
+    %put &sysmacroname: No value provided and no _program variable available;
+    %return;
+  %end;
+%end;
+%local root;
+
+/**
+  * First check we are not in the tests/macros folder (which has no subfolders)
+  * or specifically in the testsetup or testteardown services
+  */
+%if %index(&pgm,/tests/macros/)
+or %index(&pgm,/tests/testsetup)
+or %index(&pgm,/tests/testteardown)
+%then %do;
+  %let root=%substr(&pgm,1,%index(&pgm,/tests)-1);
+  &root
+  %return;
+%end;
+
+/**
+  * Next, move up two levels to avoid matches on subfolder or service name
+  */
+%let root=%substr(&pgm,1,%length(&pgm)-%length(%scan(&pgm,-1,/))-1);
+%let root=%substr(&root,1,%length(&root)-%length(%scan(&root,-1,/))-1);
+
+%if %index(&root,/tests/) %then %do;
+  %let root=%substr(&root,1,%index(&root,/tests/)-1);
+%end;
+%else %if %index(&root,/services) %then %do;
+  %let root=%substr(&root,1,%index(&root,/services)-1);
+%end;
+%else %if %index(&root,/jobs) %then %do;
+  %let root=%substr(&root,1,%index(&root,/jobs)-1);
+%end;
+%else %put &sysmacroname: Could not find an app location from &pgm;
+  &root
+%mend mf_getapploc ;

package/macros/mf_getattrc.sas

@@ -0,0 +1,34 @@
+/**
+  @file
+  @brief Returns a character attribute of a dataset.
+  @details Can be used in open code, eg as follows:
+
+      %put Dataset label = %mf_getattrc(sashelp.class,LABEL);
+      %put Member Type = %mf_getattrc(sashelp.class,MTYPE);
+
+  @param libds library.dataset
+  @param attr full list in [documentation](
+    https://support.sas.com/documentation/cdl/en/lrdict/64316/HTML/default/viewer.htm#a000147794.htm)
+  @return output returns result of the attrc value supplied, or -1 and log
+    message if err.
+
+  @version 9.2
+  @author Allan Bowe
+**/
+
+%macro mf_getattrc(
+    libds
+    ,attr
+)/*/STORE SOURCE*/;
+  %local dsid rc;
+  %let dsid=%sysfunc(open(&libds,is));
+  %if &dsid = 0 %then %do;
+    %put %str(WARN)ING: Cannot open %trim(&libds), system message below;
+    %put %sysfunc(sysmsg());
+    -1
+  %end;
+  %else %do;
+    %sysfunc(attrc(&dsid,&attr))
+    %let rc=%sysfunc(close(&dsid));
+  %end;
+%mend mf_getattrc;

package/macros/mf_getattrn.sas

@@ -0,0 +1,34 @@
+/**
+  @file
+  @brief Returns a numeric attribute of a dataset.
+  @details Can be used in open code, eg as follows:
+
+      %put Number of observations=%mf_getattrn(sashelp.class,NLOBS);
+      %put Number of variables = %mf_getattrn(sashelp.class,NVARS);
+
+  @param libds library.dataset
+  @param attr Common values are NLOBS and NVARS, full list in [documentation](
+  http://support.sas.com/documentation/cdl/en/lrdict/64316/HTML/default/viewer.htm#a000212040.htm)
+  @return output returns result of the attrn value supplied, or -1 and log
+    message if err.
+
+  @version 9.2
+  @author Allan Bowe
+**/
+
+%macro mf_getattrn(
+    libds
+    ,attr
+)/*/STORE SOURCE*/;
+  %local dsid rc;
+  %let dsid=%sysfunc(open(&libds,is));
+  %if &dsid = 0 %then %do;
+    %put %str(WARN)ING: Cannot open %trim(&libds), system message below;
+    %put %sysfunc(sysmsg());
+    -1
+  %end;
+  %else %do;
+    %sysfunc(attrn(&dsid,&attr))
+    %let rc=%sysfunc(close(&dsid));
+  %end;
+%mend mf_getattrn;

package/macros/mf_getengine.sas

@@ -0,0 +1,54 @@
+/**
+  @file
+  @brief Returns the engine type of a SAS library
+  @details Usage:
+
+      %put %mf_getengine(SASHELP);
+
+  returns:
+  > V9
+
+  A note is also written to the log.  The credit for this macro goes to the
+  contributors of Chris Hemedingers blog [post](
+  http://blogs.sas.com/content/sasdummy/2013/06/04/find-a-sas-library-engine/)
+
+  @param [in] libref Library reference (also accepts a 2 level libds ref).
+
+  @return output returns the library engine (uppercase) for the FIRST library
+    encountered.
+
+  @warning will only return the FIRST library engine - for concatenated
+    libraries, with different engines, inconsistent results may be encountered.
+
+  @version 9.2
+  @author Allan Bowe
+
+  <h4> Related Macros </h4>
+  @li mf_getxengine.sas
+
+**/
+/** @cond */
+
+%macro mf_getengine(libref
+)/*/STORE SOURCE*/;
+  %local dsid engnum rc engine;
+
+  /* in case the parameter is a libref.tablename, pull off just the libref */
+  %let libref = %upcase(%scan(&libref, 1, %str(.)));
+
+  %let dsid=%sysfunc(
+    open(sashelp.vlibnam(where=(libname="%upcase(&libref)")),i)
+  );
+  %if (&dsid ^= 0) %then %do;
+    %let engnum=%sysfunc(varnum(&dsid,ENGINE));
+    %let rc=%sysfunc(fetch(&dsid));
+    %let engine=%sysfunc(getvarc(&dsid,&engnum));
+    %put &libref. ENGINE is &engine.;
+    %let rc= %sysfunc(close(&dsid));
+  %end;
+
+  %upcase(&engine)
+
+%mend mf_getengine;
+
+/** @endcond */

package/macros/mf_getfilesize.sas

@@ -0,0 +1,64 @@
+/**
+  @file
+  @brief Returns the size of a file in bytes.
+  @details Provide full path/filename.extension to the file, eg:
+
+      %put %mf_getfilesize(fpath=C:\temp\myfile.txt);
+
+  or, provide a libds value as follows:
+
+      data x;do x=1 to 100000;y=x;output;end;run;
+      %put %mf_getfilesize(libds=work.x,format=yes);
+
+  Which gives:
+
+  > 2mb
+
+  @param [in] fpath= Full path and filename.  Provide this OR the libds value.
+  @param [in] libds= (0) Library.dataset value (assumes library is BASE engine)
+  @param [in] format= (NO) Set to yes to apply sizekmg. format
+
+  @returns bytes
+
+  @version 9.2
+  @author Allan Bowe
+**/
+
+%macro mf_getfilesize(fpath=,libds=0,format=NO
+)/*/STORE SOURCE*/;
+
+  %local rc fid fref bytes dsid lib vnum;
+
+  %if &libds ne 0 %then %do;
+    %let libds=%upcase(&libds);
+    %if %index(&libds,.)=0 %then %let lib=WORK;
+    %else %let lib=%scan(&libds,1,.);
+    %let dsid=%sysfunc(open(
+      sashelp.vtable(where=(libname="&lib" and memname="%scan(&libds,-1,.)")
+        keep=libname memname filesize
+      )
+    ));
+    %if (&dsid ^= 0) %then %do;
+      %let vnum=%sysfunc(varnum(&dsid,FILESIZE));
+      %let rc=%sysfunc(fetch(&dsid));
+      %let bytes=%sysfunc(getvarn(&dsid,&vnum));
+      %let rc= %sysfunc(close(&dsid));
+    %end;
+    %else %put &sysmacroname: &libds could not be opened! %sysfunc(sysmsg());
+  %end;
+  %else %do;
+    %let rc=%sysfunc(filename(fref,&fpath));
+    %let fid=%sysfunc(fopen(&fref));
+    %let bytes=%sysfunc(finfo(&fid,File Size (bytes)));
+    %let rc=%sysfunc(fclose(&fid));
+    %let rc=%sysfunc(filename(fref));
+  %end;
+
+  %if &format=NO %then %do;
+    &bytes
+  %end;
+  %else %do;
+    %sysfunc(INPUTN(&bytes, best.),sizekmg.)
+  %end;
+
+%mend mf_getfilesize ;

package/macros/mf_getfmtlist.sas

@@ -0,0 +1,61 @@
+/**
+  @file
+  @brief Returns a distinct list of formats from a table
+  @details Reads the dataset header and returns a distinct list of formats
+  applied.
+
+        %put NOTE- %mf_getfmtlist(sashelp.prdsale);
+        %put NOTE- %mf_getfmtlist(sashelp.shoes);
+        %put NOTE- %mf_getfmtlist(sashelp.demographics);
+
+  returns:
+
+  > DOLLAR $CHAR W MONNAME
+  > $CHAR BEST DOLLAR
+  > BEST Z $CHAR COMMA PERCENTN
+
+
+  @param [in] libds Two part library.dataset reference.
+
+  <h4> SAS Macros </h4>
+  @li mf_getfmtname.sas
+
+  @version 9.2
+  @author Allan Bowe
+
+**/
+
+%macro mf_getfmtlist(libds
+)/*/STORE SOURCE*/;
+/* declare local vars */
+%local out dsid nvars x rc fmt;
+
+/* open dataset in macro */
+%let dsid=%sysfunc(open(&libds));
+
+/* continue if dataset exists */
+%if &dsid %then %do;
+  /* loop each variable in the dataset */
+  %let nvars=%sysfunc(attrn(&dsid,NVARS));
+  %do x=1 %to &nvars;
+    /* grab format and check it exists */
+    %let fmt=%sysfunc(varfmt(&dsid,&x));
+    %if %quote(&fmt) ne %quote() %then %let fmt=%mf_getfmtname(&fmt);
+    %else %do;
+      /* assign default format depending on variable type */
+      %if %sysfunc(vartype(&dsid, &x))=C %then %let fmt=$CHAR;
+      %else %let fmt=BEST;
+    %end;
+    /* concatenate unique list of formats */
+    %if %sysfunc(indexw(&out,&fmt,%str( )))=0 %then %let out=&out &fmt;
+  %end;
+  %let rc=%sysfunc(close(&dsid));
+%end;
+%else %do;
+  %put &sysmacroname: Unable to open &libds (rc=&dsid);
+  %put &sysmacroname: SYSMSG= %sysfunc(sysmsg());
+  %let rc=%sysfunc(close(&dsid));
+%end;
+/* send them out without spaces or quote markers */
+%do;%unquote(&out)%end;
+%mend mf_getfmtlist;

package/macros/mf_getfmtname.sas

@@ -0,0 +1,44 @@
+/**
+  @file
+  @brief Extracts a format name from a fully defined format
+  @details Converts formats in like $thi3. and th13.2 $THI and TH.
+  Usage:
+
+      %put %mf_getfmtname(8.);
+      %put %mf_getfmtname($4.);
+      %put %mf_getfmtname(comma14.10);
+
+  Returns:
+
+  > W
+  > $CHAR
+  > COMMA
+
+  Note that system defaults are inferred from the values provided.
+
+  @param [in] fmt The fully defined format. If left blank, nothing is returned.
+
+  @returns The name (without width or decimal) of the format.
+
+  @version 9.2
+  @author Allan Bowe
+
+**/
+
+%macro mf_getfmtname(fmt
+)/*/STORE SOURCE*/ /minoperator mindelimiter=' ';
+
+%local out dsid nvars x rc fmt;
+
+/* extract actual format name from the format definition */
+%let fmt=%scan(&fmt,1,.);
+%do %while(%substr(&fmt,%length(&fmt),1) in 1 2 3 4 5 6 7 8 9 0);
+  %if %length(&fmt)=1 %then %let fmt=W;
+  %else %let fmt=%substr(&fmt,1,%length(&fmt)-1);
+%end;
+
+%if &fmt=$ %then %let fmt=$CHAR;
+
+/* send them out without spaces or quote markers */
+%do;%unquote(%upcase(&fmt))%end;
+%mend mf_getfmtname;

package/macros/mf_getkeyvalue.sas

@@ -0,0 +1,32 @@
+/**
+  @file
+  @brief retrieves a key value pair from a control dataset
+  @details By default, control dataset is work.mp_setkeyvalue.  Usage:
+
+      %mp_setkeyvalue(someindex,22,type=N)
+      %put %mf_getkeyvalue(someindex)
+
+
+  @param key Provide a key on which to perform the lookup
+  @param libds= define the target table which holds the parameters
+
+  @version 9.2
+  @author Allan Bowe
+**/
+
+%macro mf_getkeyvalue(key,libds=work.mp_setkeyvalue
+)/*/STORE SOURCE*/;
+%local ds dsid key valc valn type rc;
+%let dsid=%sysfunc(open(&libds(where=(key="&key"))));
+%syscall set(dsid);
+%let rc = %sysfunc(fetch(&dsid));
+%let rc = %sysfunc(close(&dsid));
+
+%if &type=N %then %do;
+  &valn
+%end;
+%else %if &type=C %then %do;
+  &valc
+%end;
+%else %put %str(ERR)OR: Unable to find key &key in ds &libds;
+%mend mf_getkeyvalue;

package/macros/mf_getplatform.sas

@@ -0,0 +1,75 @@
+/**
+  @file mf_getplatform.sas
+  @brief Returns platform specific variables
+  @details Enables platform specific variables to be returned
+
+      %put %mf_getplatform();
+
+  returns one of:
+
+  @li SASMETA
+  @li SASVIYA
+  @li SASJS
+  @li BASESAS
+
+  @param switch the param for which to return a platform specific variable
+
+  <h4> SAS Macros </h4>
+  @li mf_mval.sas
+  @li mf_trimstr.sas
+
+  @version 9.4 / 3.4
+  @author Allan Bowe
+**/
+
+%macro mf_getplatform(switch
+)/*/STORE SOURCE*/;
+%local a b c;
+%if &switch.NONE=NONE %then %do;
+  %if %symexist(sasjsprocessmode) %then %do;
+    %if &sasjsprocessmode=Stored Program %then %do;
+      SASJS
+      %return;
+    %end;
+  %end;
+  %if %symexist(sysprocessmode) %then %do;
+    %if "&sysprocessmode"="SAS Object Server"
+    or "&sysprocessmode"= "SAS Compute Server" %then %do;
+        SASVIYA
+    %end;
+    %else %if "&sysprocessmode"="SAS Stored Process Server"
+      or "&sysprocessmode"="SAS Workspace Server"
+    %then %do;
+      SASMETA
+      %return;
+    %end;
+    %else %do;
+      BASESAS
+      %return;
+    %end;
+  %end;
+  %else %if %symexist(_metaport) or %symexist(_metauser) %then %do;
+    SASMETA
+    %return;
+  %end;
+  %else %do;
+    BASESAS
+    %return;
+  %end;
+%end;
+%else %if &switch=SASSTUDIO %then %do;
+  /* return the version of SAS Studio else 0 */
+  %if %mf_mval(_CLIENTAPP)=%str(SAS Studio) %then %do;
+    %let a=%mf_mval(_CLIENTVERSION);
+    %let b=%scan(&a,1,.);
+    %if %eval(&b >2) %then %do;
+      &b
+    %end;
+    %else 0;
+  %end;
+  %else 0;
+%end;
+%else %if &switch=VIYARESTAPI %then %do;
+  %mf_trimstr(%sysfunc(getoption(servicesbaseurl)),/)
+%end;
+%mend mf_getplatform;

package/macros/mf_getquotedstr.sas

@@ -0,0 +1,57 @@
+/**
+  @file
+  @brief Adds custom quotes / delimiters to a  delimited string
+  @details Can be used in open code, eg as follows:
+
+      %put %mf_getquotedstr(blah   blah  blah);
+
+  which returns:
+> 'blah','blah','blah'
+
+  Alternatively:
+
+      %put %mf_getquotedstr(these words are double quoted,quote=D)
+
+  for:
+> "these","words","are","double","quoted"
+
+  @param [in] in_str The unquoted, spaced delimited string to transform
+  @param [in] dlm= (,) The delimeter to be applied to the output (default comma)
+  @param [in] indlm= ( ) The delimeter used for the input (default is space)
+  @param [in] quote= (S) The quote mark to apply (S=Single, D=Double, N=None).
+    If any other value than uppercase S or D is supplied, then that value will
+    be used as the quoting character.
+  @return output returns a string with the newly quoted / delimited output.
+
+  @version 9.2
+  @author Allan Bowe
+**/
+
+
+%macro mf_getquotedstr(IN_STR
+  ,DLM=%str(,)
+  ,QUOTE=S
+  ,indlm=%str( )
+)/*/STORE SOURCE*/;
+  /* credit Rowland Hale  - byte34 is double quote, 39 is single quote */
+  %if &quote=S %then %let quote=%qsysfunc(byte(39));
+  %else %if &quote=D %then %let quote=%qsysfunc(byte(34));
+  %else %if &quote=N %then %let quote=;
+  %local i item buffer;
+  %let i=1;
+  %do %while (%qscan(&IN_STR,&i,%str(&indlm)) ne %str() ) ;
+    %let item=%qscan(&IN_STR,&i,%str(&indlm));
+    %if %bquote(&QUOTE) ne %then %let item=&QUOTE%qtrim(&item)&QUOTE;
+    %else %let item=%qtrim(&item);
+
+    %if (&i = 1) %then %let buffer =%qtrim(&item);
+    %else %let buffer =&buffer&DLM%qtrim(&item);
+
+    %let i = %eval(&i+1);
+  %end;
+
+  %let buffer=%sysfunc(coalescec(%qtrim(&buffer),&QUOTE&QUOTE));
+
+  &buffer
+
+%mend mf_getquotedstr;

package/macros/mf_getschema.sas

@@ -0,0 +1,43 @@
+/**
+  @file mf_getschema.sas
+  @brief Returns the database schema of a SAS library
+  @details Usage:
+
+      %put %mf_getschema(MYDB);
+
+  returns:
+  > dbo
+
+  @param libref Library reference (also accepts a 2 level libds ref).
+
+  @return output returns the library schema for the FIRST library encountered
+
+  @warning will only return the FIRST library schema - for concatenated
+    libraries, with different schemas, inconsistent results may be encountered.
+
+  @version 9.2
+  @author Allan Bowe
+  @cond
+**/
+
+%macro mf_getschema(libref
+)/*/STORE SOURCE*/;
+  %local dsid vnum rc schema;
+  /* in case the parameter is a libref.tablename, pull off just the libref */
+  %let libref = %upcase(%scan(&libref, 1, %str(.)));
+  %let dsid=%sysfunc(open(sashelp.vlibnam(where=(
+    libname="%upcase(&libref)" and sysname='Schema/Owner'
+  )),i));
+  %if (&dsid ^= 0) %then %do;
+    %let vnum=%sysfunc(varnum(&dsid,SYSVALUE));
+    %let rc=%sysfunc(fetch(&dsid));
+    %let schema=%sysfunc(getvarc(&dsid,&vnum));
+    %put &libref. schema is &schema.;
+    %let rc= %sysfunc(close(&dsid));
+  %end;
+
+  &schema
+
+%mend mf_getschema;
+
+/** @endcond */

package/macros/mf_getuniquefileref.sas

@@ -0,0 +1,60 @@
+/**
+  @file
+  @brief Assigns and returns an unused fileref
+  @details  Using the native approach for assigning filerefs fails as some
+  procedures (such as proc http) do not recognise the temporary names (starting
+  with a hash), returning a message such as:
+
+  > ERROR 22-322: Expecting a name.
+
+  This macro works by attempting a random fileref (with a prefix), seeing if it
+  is already assigned, and if not - returning the fileref.
+
+  If your process can accept filerefs with the hash (#) prefix, then set
+  `prefix=0` to revert to the native approach - which is significantly faster
+  when there are a lot of filerefs in a session.
+
+  Use as follows:
+
+      %let fileref1=%mf_getuniquefileref();
+      %let fileref2=%mf_getuniquefileref(prefix=0);
+      %put &fileref1 &fileref2;
+
+  which returns filerefs similar to:
+
+> _7432233 #LN00070
+
+  @param [in] prefix= (_) first part of fileref. Remember that filerefs can only
+    be 8 characters, so a 7 letter prefix would mean `maxtries` should be 10.
+    if using zero (0) as the prefix, a native assignment is used.
+  @param [in] maxtries= (1000) the last part of the libref. Must be an integer.
+  @param [in] lrecl= (32767) Provide a default lrecl with which to initialise
+    the generated fileref.
+
+  @version 9.2
+  @author Allan Bowe
+**/
+
+%macro mf_getuniquefileref(prefix=_,maxtries=1000,lrecl=32767);
+  %local rc fname;
+  %if &prefix=0 %then %do;
+    %let rc=%sysfunc(filename(fname,,temp,lrecl=&lrecl));
+    %if &rc %then %put %sysfunc(sysmsg());
+    &fname
+  %end;
+  %else %do;
+    %local x len;
+    %let len=%eval(8-%length(&prefix));
+    %let x=0;
+    %do x=0 %to &maxtries;
+      %let fname=&prefix%substr(%sysfunc(ranuni(0)),3,&len);
+      %if %sysfunc(fileref(&fname)) > 0 %then %do;
+        %let rc=%sysfunc(filename(fname,,temp,lrecl=&lrecl));
+        %if &rc %then %put %sysfunc(sysmsg());
+        &fname
+        %return;
+      %end;
+    %end;
+    %put unable to find available fileref after &maxtries attempts;
+  %end;
+%mend mf_getuniquefileref;

package/macros/mf_getuniquelibref.sas

@@ -0,0 +1,57 @@
+/**
+  @file
+  @brief Returns an unused libref
+  @details Use as follows:
+
+      libname mclib0 (work);
+      libname mclib1 (work);
+      libname mclib2 (work);
+
+      %let libref=%mf_getuniquelibref();
+      %put &=libref;
+
+  which returns:
+
+> mclib3
+
+  A blank value is returned if no usable libname is determined.
+
+  @param [in] prefix= (mclib) first part of the returned libref. As librefs can
+    be as long as 8 characters, a maximum length of 7 characters is premitted
+    for this prefix.
+  @param [in] maxtries= Deprecated parameter. Remains here to ensure a
+    non-breaking change.  Will be removed in v5.
+
+  @version 9.2
+  @author Allan Bowe
+**/
+
+%macro mf_getuniquelibref(prefix=mclib,maxtries=1000);
+  %local x;
+
+  %if ( %length(&prefix) gt 7 ) %then %do;
+    %put %str(ERR)OR: The prefix parameter cannot exceed 7 characters.;
+    0
+    %return;
+  %end;
+  %else %if (%sysfunc(NVALID(&prefix,v7))=0) %then %do;
+    %put %str(ERR)OR: Invalid prefix (&prefix);
+    0
+    %return;
+  %end;
+
+  /* Set maxtries equal to '10 to the power of [# unused characters] - 1' */
+  %let maxtries=%eval(10**(8-%length(&prefix))-1);
+
+  %do x = 0 %to &maxtries;
+    %if %sysfunc(libref(&prefix&x)) ne 0 %then %do;
+      &prefix&x
+      %return;
+    %end;
+    %let x = %eval(&x + 1);
+  %end;
+
+  %put %str(ERR)OR: No usable libref in range &prefix.0-&maxtries;
+  %put %str(ERR)OR- Try reducing the prefix or deleting some libraries!;
+  0
+%mend mf_getuniquelibref;