@sasjs/utils 2.48.2 → 2.49.1

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;

package/macros/mf_getvarcount.sas

@@ -0,0 +1,49 @@
+/**
+  @file
+  @brief Returns number of variables in a dataset
+  @details Useful to identify those renagade datasets that have no columns!
+  Can also be used to count for numeric, or character columns
+
+      %put Number of Variables=%mf_getvarcount(sashelp.class);
+      %put Character Variables=%mf_getvarcount(sashelp.class,typefilter=C);
+      %put Numeric Variables = %mf_getvarcount(sashelp.class,typefilter=N);
+
+  returns:
+  > Number of Variables=4
+
+
+  @param [in] libds Two part dataset (or view) reference.
+  @param [in] typefilter= (A) Filter for certain types of column.  Valid values:
+    @li A Count All columns
+    @li C Count Character columns only
+    @li N Count Numeric columns only
+
+  @version 9.2
+  @author Allan Bowe
+
+**/
+
+%macro mf_getvarcount(libds,typefilter=A
+)/*/STORE SOURCE*/;
+  %local dsid nvars rc outcnt x;
+  %let dsid=%sysfunc(open(&libds));
+  %let nvars=.;
+  %let outcnt=0;
+  %let typefilter=%upcase(&typefilter);
+  %if &dsid %then %do;
+    %let nvars=%sysfunc(attrn(&dsid,NVARS));
+    %if &typefilter=A %then %let outcnt=&nvars;
+    %else %if &nvars>0 %then %do x=1 %to &nvars;
+      /* increment based on variable type */
+      %if %sysfunc(vartype(&dsid,&x))=&typefilter %then %do;
+        %let outcnt=%eval(&outcnt+1);
+      %end;
+    %end;
+    %let rc=%sysfunc(close(&dsid));
+  %end;
+  %else %do;
+    %put unable to open &libds (rc=&dsid);
+    %let rc=%sysfunc(close(&dsid));
+  %end;
+  &outcnt
+%mend mf_getvarcount;

package/macros/mf_getvarformat.sas

@@ -0,0 +1,72 @@
+/**
+  @file
+  @brief Returns the format of a variable
+  @details Uses varfmt function to identify the format of a particular variable.
+  Usage:
+
+      data test;
+        format str1 $1.  num1 datetime19.;
+        str2='hello mum!'; num2=666;
+        stop;
+      run;
+      %put %mf_getVarFormat(test,str1);
+      %put %mf_getVarFormat(work.test,num1);
+      %put %mf_getVarFormat(test,str2,force=1);
+      %put %mf_getVarFormat(work.test,num2,force=1);
+      %put %mf_getVarFormat(test,renegade);
+
+  returns:
+
+      $1.
+      DATETIME19.
+      $10.
+      8.
+      NOTE: Variable renegade does not exist in test
+
+  @param [in] libds Two part dataset (or view) reference.
+  @param [in] var Variable name for which a format should be returned
+  @param [in] force=(0) Set to 1 to supply a default if the variable has no format
+  @returns outputs format
+
+  @author Allan Bowe
+  @version 9.2
+**/
+
+%macro mf_getVarFormat(libds /* two level ds name */
+      , var /* variable name from which to return the format */
+      , force=0
+)/*/STORE SOURCE*/;
+  %local dsid vnum vformat rc vlen vtype;
+  /* Open dataset */
+  %let dsid = %sysfunc(open(&libds));
+  %if &dsid > 0 %then %do;
+    /* Get variable number */
+    %let vnum = %sysfunc(varnum(&dsid, &var));
+    /* Get variable format */
+    %if(&vnum > 0) %then %let vformat=%sysfunc(varfmt(&dsid, &vnum));
+    %else %do;
+      %put NOTE: Variable &var does not exist in &libds;
+      %let rc = %sysfunc(close(&dsid));
+      %return;
+    %end;
+  %end;
+  %else %do;
+    %put &sysmacroname: dataset &libds not opened! (rc=&dsid);
+    %put &sysmacroname: %sysfunc(sysmsg());
+    %return;
+  %end;
+
+  /* supply a default if no format available */
+  %if %length(&vformat)<2 & &force=1 %then %do;
+    %let vlen = %sysfunc(varlen(&dsid, &vnum));
+    %let vtype = %sysfunc(vartype(&dsid, &vnum.));
+    %if &vtype=C %then %let vformat=$&vlen..;
+    %else %let vformat=best.;
+  %end;
+
+
+  /* Close dataset */
+  %let rc = %sysfunc(close(&dsid));
+  /* Return variable format */
+  &vformat
+%mend mf_getVarFormat;

package/macros/mf_getvarlen.sas

@@ -0,0 +1,56 @@
+/**
+  @file
+  @brief Returns the length of a variable
+  @details Uses varlen function to identify the length of a particular variable.
+  Usage:
+
+      data test;
+        format str $1.  num datetime19.;
+        stop;
+      run;
+      %put %mf_getVarLen(test,str);
+      %put %mf_getVarLen(work.test,num);
+      %put %mf_getVarLen(test,renegade);
+
+  returns:
+
+      1
+      8
+      NOTE: Variable renegade does not exist in test
+
+  @param libds Two part dataset (or view) reference.
+  @param var Variable name for which a length should be returned
+  @returns outputs length
+
+  @author Allan Bowe
+  @version 9.2
+
+**/
+
+%macro mf_getVarLen(libds /* two level ds name */
+      , var /* variable name from which to return the length */
+)/*/STORE SOURCE*/;
+  %local dsid vnum vlen rc;
+  /* Open dataset */
+  %let dsid = %sysfunc(open(&libds));
+  %if &dsid > 0 %then %do;
+    /* Get variable number */
+    %let vnum = %sysfunc(varnum(&dsid, &var));
+    /* Get variable format */
+    %if(&vnum > 0) %then %let vlen = %sysfunc(varlen(&dsid, &vnum));
+    %else %do;
+      %put NOTE: Variable &var does not exist in &libds;
+      %let vlen = %str( );
+    %end;
+  %end;
+  %else %do;
+    %put &sysmacroname: dataset &libds not opened! (rc=&dsid);
+    %put &sysmacroname: %sysfunc(sysmsg());
+    %return;
+  %end;
+
+  /* Close dataset */
+  %let rc = %sysfunc(close(&dsid));
+  /* Return variable format */
+  &vlen
+%mend mf_getVarLen;

package/macros/mf_getvarlist.sas

@@ -0,0 +1,74 @@
+/**
+  @file
+  @brief Returns dataset variable list direct from header
+  @details WAY faster than dictionary tables or sas views, and can
+    also be called in macro logic (is pure macro). Can be used in open code,
+    eg as follows:
+
+        %put List of Variables=%mf_getvarlist(sashelp.class);
+
+  returns:
+  > List of Variables=Name Sex Age Height Weight
+
+  For a seperated list of column values:
+
+        %put %mf_getvarlist(sashelp.class,dlm=%str(,),quote=double);
+
+  returns:
+  > "Name","Sex","Age","Height","Weight"
+
+  @param [in] libds Two part dataset (or view) reference.
+  @param [in] dlm= ( ) Provide a delimiter (eg comma or space) to separate the
+    variables
+  @param [in] quote= (none) use either DOUBLE or SINGLE to quote the results
+  @param [in] typefilter= (A) Filter for certain types of column.  Valid values:
+    @li A Return All columns
+    @li C Return Character columns
+    @li N Return Numeric columns
+
+  @version 9.2
+  @author Allan Bowe
+
+**/
+
+%macro mf_getvarlist(libds
+      ,dlm=%str( )
+      ,quote=no
+      ,typefilter=A
+)/*/STORE SOURCE*/;
+  /* declare local vars */
+  %local outvar dsid nvars x rc dlm q var vtype;
+
+  /* credit Rowland Hale  - byte34 is double quote, 39 is single quote */
+  %if %upcase(&quote)=DOUBLE %then %let q=%qsysfunc(byte(34));
+  %else %if %upcase(&quote)=SINGLE %then %let q=%qsysfunc(byte(39));
+  /* open dataset in macro */
+  %let dsid=%sysfunc(open(&libds));
+
+  %if &dsid %then %do;
+    %let nvars=%sysfunc(attrn(&dsid,NVARS));
+    %if &nvars>0 %then %do;
+      /* add variables with supplied delimeter */
+      %do x=1 %to &nvars;
+        /* get variable type */
+        %let vtype=%sysfunc(vartype(&dsid,&x));
+        %if &vtype=&typefilter or &typefilter=A %then %do;
+          %let var=&q.%sysfunc(varname(&dsid,&x))&q.;
+          %if &var=&q&q %then %do;
+            %put &sysmacroname: Empty column found in &libds!;
+            %let var=&q. &q.;
+          %end;
+          %if %quote(&outvar)=%quote() %then %let outvar=&var;
+          %else %let outvar=&outvar.&dlm.&var.;
+        %end;
+      %end;
+    %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;
+  %do;%unquote(&outvar)%end;
+%mend mf_getvarlist;

package/macros/mf_getvarnum.sas

@@ -0,0 +1,58 @@
+/**
+  @file
+  @brief Returns the position of a variable in dataset (varnum attribute).
+  @details Uses varnum function to determine position.
+
+Usage:
+
+    data work.test;
+      format str $1.  num datetime19.;
+      stop;
+    run;
+    %put %mf_getVarNum(work.test,str);
+    %put %mf_getVarNum(work.test,num);
+    %put %mf_getVarNum(work.test,renegade);
+
+returns:
+
+  > 1
+
+  > 2
+
+  > NOTE: Variable renegade does not exist in test
+
+  @param libds Two part dataset (or view) reference.
+  @param var Variable name for which a position should be returned
+
+  @author Allan Bowe
+  @version 9.2
+
+**/
+
+%macro mf_getVarNum(libds /* two level ds name */
+      , var /* variable name from which to return the format */
+)/*/STORE SOURCE*/;
+  %local dsid vnum rc;
+  /* Open dataset */
+  %let dsid = %sysfunc(open(&libds));
+  %if &dsid > 0 %then %do;
+    /* Get variable number */
+    %let vnum = %sysfunc(varnum(&dsid, &var));
+    %if(&vnum <= 0) %then %do;
+      %put NOTE: Variable &var does not exist in &libds;
+      %let vnum = %str( );
+    %end;
+  %end;
+  %else %do;
+    %put &sysmacroname: dataset &libds not opened! (rc=&dsid);
+    %put &sysmacroname: %sysfunc(sysmsg());
+    %return;
+  %end;
+
+  /* Close dataset */
+  %let rc = %sysfunc(close(&dsid));
+
+  /* Return variable number */
+    &vnum.
+
+%mend mf_getVarNum;

package/macros/mf_getvartype.sas

@@ -0,0 +1,52 @@
+/**
+  @file
+  @brief Returns variable type - Character (C) or Numeric (N)
+  @details
+Usage:
+
+      data test;
+        length str $1.  num 8.;
+        stop;
+      run;
+      %put %mf_getvartype(test,str);
+      %put %mf_getvartype(work.test,num);
+
+
+
+  @param libds Two part dataset (or view) reference.
+  @param var the variable name to be checked
+  @return output returns C or N depending on variable type.  If variable
+    does not exist then a blank is returned and a note is written to the log.
+
+  @version 9.2
+  @author Allan Bowe
+
+**/
+
+%macro mf_getvartype(libds /* two level name */
+      , var /* variable name from which to return the type */
+)/*/STORE SOURCE*/;
+  %local dsid vnum vtype rc;
+  /* Open dataset */
+  %let dsid = %sysfunc(open(&libds));
+  %if &dsid. > 0 %then %do;
+    /* Get variable number */
+    %let vnum = %sysfunc(varnum(&dsid, &var));
+    /* Get variable type (C/N) */
+    %if(&vnum. > 0) %then %let vtype = %sysfunc(vartype(&dsid, &vnum.));
+    %else %do;
+      %put NOTE: Variable &var does not exist in &libds;
+      %let vtype = %str( );
+    %end;
+  %end;
+  %else %do;
+    %put &sysmacroname: dataset &libds not opened! (rc=&dsid);
+    %put &sysmacroname: %sysfunc(sysmsg());
+    %return;
+  %end;
+
+  /* Close dataset */
+  %let rc = %sysfunc(close(&dsid));
+  /* Return variable type */
+  &vtype
+%mend mf_getvartype;

package/macros/mf_getxengine.sas

@@ -0,0 +1,43 @@
+/**
+  @file
+  @brief Returns the engine type of a SAS fileref
+  @details Queries sashelp.vextfl to get the xengine value.
+  Usage:
+
+      filename feng temp;
+      %put %mf_getxengine(feng);
+
+  returns:
+  > TEMP
+
+  @param fref The fileref to check
+
+  @returns The XENGINE value in sashelp.vextfl or 0 if not found.
+
+  @version 9.2
+  @author Allan Bowe
+
+  <h4> Related Macros </h4>
+  @li mf_getengine.sas
+
+**/
+
+%macro mf_getxengine(fref
+)/*/STORE SOURCE*/;
+  %local dsid engnum rc engine;
+
+  %let dsid=%sysfunc(
+    open(sashelp.vextfl(where=(fileref="%upcase(&fref)")),i)
+  );
+  %if (&dsid ^= 0) %then %do;
+    %let engnum=%sysfunc(varnum(&dsid,XENGINE));
+    %let rc=%sysfunc(fetch(&dsid));
+    %let engine=%sysfunc(getvarc(&dsid,&engnum));
+    %* put &fref. ENGINE is &engine.;
+    %let rc= %sysfunc(close(&dsid));
+  %end;
+  %else %let engine=0;
+
+  &engine
+
+%mend mf_getxengine;

package/macros/mf_increment.sas

@@ -0,0 +1,29 @@
+/**
+  @file
+  @brief Increments a macro variable
+  @details Useful outside of do-loops - will increment a macro variable every
+  time it is called.
+
+  Example:
+
+      %let cnt=1;
+      %put We have run %mf_increment(cnt) lines;
+      %put Now we have run %mf_increment(cnt) lines;
+      %put There are %mf_increment(cnt) lines in total;
+
+  @param [in] MACRO_NAME the name of the macro variable to increment
+  @param [in] ITER= The amount to add or subtract to the macro
+
+  <h4> Related Files </h4>
+  @li mf_increment.test.sas
+
+**/
+
+%macro mf_increment(macro_name,incr=1);
+
+  /* iterate the value */
+  %let &macro_name=%eval(&&&macro_name+&incr);
+  /* return the value */
+  &&&macro_name
+
+%mend mf_increment;

package/macros/mf_isblank.sas

@@ -0,0 +1,27 @@
+/**
+  @file mf_isblank.sas
+  @brief Checks whether a macro variable is empty (blank)
+  @details Simply performs:
+
+      %sysevalf(%superq(param)=,boolean)
+
+  Usage:
+
+      %put mf_isblank(&var);
+
+  inspiration:
+  https://support.sas.com/resources/papers/proceedings09/022-2009.pdf
+
+  @param param VALUE to be checked
+
+  @return output returns 1 (if blank) else 0
+
+  @version 9.2
+**/
+
+%macro mf_isblank(param
+)/*/STORE SOURCE*/;
+
+  %sysevalf(%superq(param)=,boolean)
+
+%mend mf_isblank;

package/macros/mf_isdir.sas

@@ -0,0 +1,34 @@
+/**
+  @file
+  @brief Checks whether a path is a valid directory
+  @details
+  Usage:
+
+      %let isdir=%mf_isdir(/tmp);
+
+  With thanks and full credit to Andrea Defronzo -
+  https://www.linkedin.com/in/andrea-defronzo-b1a47460/
+
+  @param path full path of the file/directory to be checked
+
+  @return output returns 1 if path is a directory, 0 if it is not
+
+  @version 9.2
+**/
+
+%macro mf_isdir(path
+)/*/STORE SOURCE*/;
+  %local rc did is_directory fref_t;
+
+  %let is_directory = 0;
+  %let rc = %sysfunc(filename(fref_t, %superq(path)));
+  %let did = %sysfunc(dopen(&fref_t.));
+  %if &did. ^= 0 %then %do;
+    %let is_directory = 1;
+    %let rc = %sysfunc(dclose(&did.));
+  %end;
+  %let rc = %sysfunc(filename(fref_t));
+
+  &is_directory
+
+%mend mf_isdir;

package/macros/mf_isint.sas

@@ -0,0 +1,36 @@
+/**
+  @file
+  @brief Returns 1 if the variable contains only digits 0-9, else 0
+  @details Note that numerics containing any punctuation (including decimals
+    or exponents) will be flagged zero.
+
+  If you'd like support for this, then do raise an issue (or even better, a
+  pull request!)
+
+  Usage:
+
+      %put %mf_isint(1) returns 1;
+      %put %mf_isint(1.1) returns 0;
+      %put %mf_isint(%str(1,1)) returns 0;
+
+  @param [in] arg input value to check
+
+  @version 9.2
+**/
+
+%macro mf_isint(arg
+)/*/STORE SOURCE*/;
+
+  /* blank val is not an integer */
+  %if "&arg"="" %then %do;0%return;%end;
+
+  /* remove minus sign if exists */
+  %local val;
+  %if "%substr(%str(&arg),1,1)"="-" %then %let val=%substr(%str(&arg),2);
+  %else %let val=&arg;
+
+  /* check remaining chars */
+  %if %sysfunc(findc(%str(&val),,kd)) %then %do;0%end;
+  %else %do;1%end;
+
+%mend mf_isint;

package/macros/mf_islibds.sas

@@ -0,0 +1,40 @@
+/**
+  @file
+  @brief Checks whether a string follows correct library.dataset format
+  @details Many macros in the core library accept a library.dataset parameter
+  referred to as 'libds'.  This macro validates the structure of that parameter,
+  eg:
+
+    @li 8 character libref?
+    @li 32 character dataset?
+    @li contains a period?
+
+  It does NOT check whether the dataset exists, or if the library is assigned.
+
+  Usage:
+
+      %put %mf_islibds(work.something)=1;
+      %put %mf_islibds(nolib)=0;
+      %put %mf_islibds(badlibref.ds)=0;
+      %put %mf_islibds(w.t.f)=0;
+
+  @param [in] libds The string to be checked
+
+  @return output Returns 1 if libds is valid, 0 if it is not
+
+  <h4> Related Macros </h4>
+  @li mf_islibds.test.sas
+  @li mp_validatecol.sas
+
+  @version 9.2
+**/
+
+%macro mf_islibds(libds
+)/*/STORE SOURCE*/;
+
+%local regex;
+%let regex=%sysfunc(prxparse(%str(/^[_a-z]\w{0,7}\.[_a-z]\w{0,31}$/i)));
+
+%sysfunc(prxmatch(&regex,&libds))
+
+%mend mf_islibds;