@sasjs/utils 2.49.0 → 2.49.1

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;

package/macros/mf_getuniquename.sas

@@ -0,0 +1,22 @@
+/**
+  @file mf_getuniquename.sas
+  @brief Returns a shortened (32 char) GUID as a valid SAS name
+  @details Use as follows:
+
+      %let myds=%mf_getuniquename();
+      %put &=myds;
+
+  which returns:
+
+> MCc59c750610321d4c8bf75faadbcd22
+
+  @param prefix= set a prefix for the new name
+
+  @version 9.3
+  @author Allan Bowe
+**/
+
+
+%macro mf_getuniquename(prefix=MC);
+&prefix.%substr(%sysfunc(compress(%sysfunc(uuidgen()),-)),1,32-%length(&prefix))
+%mend mf_getuniquename;

package/macros/mf_getuser.sas

@@ -0,0 +1,44 @@
+/**
+  @file
+  @brief Returns a userid according to session context
+  @details In a workspace session, a user is generally represented by <code>
+    &sysuserid</code> or <code>SYS_COMPUTE_SESSION_OWNER</code> if it exists.
+    In a Stored Process session, <code>&sysuserid</code>
+    resolves to a system account (default=sassrv) and instead there are several
+    metadata username variables to choose from (_metauser, _metaperson
+    ,_username, _secureusername).  The OS account is represented by
+    <code> _secureusername</code> whilst the metadata account is under <code>
+    _metaperson</code>.
+
+        %let user= %mf_getUser();
+        %put &user;
+
+  @param type - do not use, may be deprecated in a future release
+
+  @return SYSUSERID (if workspace server)
+  @return _METAPERSON (if stored process server)
+  @return SYS_COMPUTE_SESSION_OWNER (if Viya compute session)
+
+  @version 9.2
+  @author Allan Bowe
+**/
+
+%macro mf_getuser(
+)/*/STORE SOURCE*/;
+  %local user;
+
+  %if %symexist(_sasjs_username) %then %let user=&_sasjs_username;
+  %else %if %symexist(SYS_COMPUTE_SESSION_OWNER) %then %do;
+    %let user=&SYS_COMPUTE_SESSION_OWNER;
+  %end;
+  %else %if %symexist(_metaperson) %then %do;
+    %if %length(&_metaperson)=0 %then %let user=&sysuserid;
+    /* sometimes SAS will add @domain extension - remove for consistency */
+    /* but be sure to quote in case of usernames with commas */
+    %else %let user=%unquote(%scan(%quote(&_metaperson),1,@));
+  %end;
+  %else %let user=&sysuserid;
+
+  %quote(&user)
+
+%mend mf_getuser;

package/macros/mf_getvalue.sas

@@ -0,0 +1,36 @@
+/**
+  @file
+  @brief Retrieves a value from a dataset.  If no filter supplied, then first
+    record is used.
+  @details Be sure to <code>%quote()</code> your where clause.  Example usage:
+
+      %put %mf_getvalue(sashelp.class,name,filter=%quote(age=15));
+      %put %mf_getvalue(sashelp.class,name);
+
+  <h4> SAS Macros </h4>
+  @li mf_getattrn.sas
+
+  <h4> Related Macros </h4>
+  @li mp_setkeyvalue.sas
+
+  @param libds dataset to query
+  @param variable the variable which contains the value to return.
+  @param filter contents of where clause
+
+  @version 9.2
+  @author Allan Bowe
+**/
+
+%macro mf_getvalue(libds,variable,filter=1
+)/*/STORE SOURCE*/;
+  %if %mf_getattrn(&libds,NLOBS)>0 %then %do;
+    %local dsid rc &variable;
+    %let dsid=%sysfunc(open(&libds(where=(&filter))));
+    %syscall set(dsid);
+    %let rc = %sysfunc(fetch(&dsid));
+    %let rc = %sysfunc(close(&dsid));
+
+    %trim(&&&variable)
+
+  %end;
+%mend mf_getvalue;